Authenticate with an API key

Every call to the API carries an API key in the X-Api-Key header. There’s no other way to sign in to the API: no token exchange, no Authorization header.

curl -i https://app.samesake.co.uk/api/v1/records/by-source-id/CRM-10042 \
  -H "X-Api-Key: mk_abcd1234_0123456789abcdefghjkmnpqrstvwxyz"

Try it in the API reference

The key in that example is a placeholder. Use the one Samesake gave you.

What a key is

A key belongs to one source, which is one of your systems. It can create, change, read and delete that source’s records, and nothing else. A key for your CRM can’t touch your shop’s records, and can’t read the identity map.

A key looks like mk_, then eight letters and digits, then an underscore, then 32 more letters and digits. The first part, mk_ and the eight characters, is how Samesake tells your keys apart: the app lists each key as mk_ and those eight characters followed by an ellipsis. The rest is the secret. Samesake keeps only a scrambled copy of the key, so it can show it to you once, when you issue it, and never again.

Send the key over HTTPS only.

Issue a key

Only an admin can issue keys.

1. Sign in at app.samesake.co.uk, then open Admin and Sources.
2. On the source’s row, choose Issue API key.
3. Copy the key from the box at the top of the page, before you leave it.

A source can have two active keys at a time. If it already has two, revoke one before you issue another.

Rotate a key

Keys don’t expire, but it’s good practice to replace each one about once a year. The Sources page marks a key that’s over a year old. You can rotate without a gap, because a source can have two keys:

1. Issue a second key for the source.
2. Switch your system over to the new key.
3. Check the system is sending records, with the new key.
4. Revoke the old key.

Revoke a key

On the source’s row, choose Revoke beside the key, and confirm. Anything still using that key is refused from then on: the API answers 401 Unauthorized.

Revoke a key straight away if it may have leaked. Issue its replacement first if the system has to keep running.

Keep keys safe

Anyone who has a key can change or delete every record in its source. Treat it like a password.

• Call the API from a server. Never put a key in a web page, a mobile app or any code that runs on someone else’s device. The API allows browser calls only from this documentation site’s origin. A browser on any other site gets no CORS headers, so it can’t read the API’s answers.
• Keep keys out of your code. Read the key from an environment variable or your platform’s secret store, not from a file you commit. The examples in these guides paste the key into the command to keep them short: in your own scripts, use "X-Api-Key: $SAMESAKE_API_KEY" and set the variable.
• Don’t share a key between systems. Register one source for each system, so a leak is contained and you can revoke one system without stopping the rest.
• Don’t paste keys into tickets, chats or logs. If you ask us about an error, quote the traceId from the response, never the key.

What a refused key looks like

A missing, mistyped or revoked key gets 401 Unauthorized, with a problem details body:

Response: 401 Unauthorized

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Check the header name (X-Api-Key), that the key is the whole string with no spaces, and that it hasn’t been revoked.

Feed keys are different

The identity map, which lists every record’s ID against its person ID, is read through a separate OData feed, for Power BI, Excel and Azure Data Factory. It has its own feed keys, issued on the same Sources page. A feed key is read-only, uses Basic authentication, and can’t send records. An API key can’t read the feed. Keep the two apart.

Sandboxes

A sandbox is a separate test copy of your account: an add-on at £50 a month on any plan, with one included on Enterprise. Sandboxes arrive with paid plans.

Until you have one, test with made-up people, such as the ones in these guides, and delete them when you’ve finished. Delete a record shows how.