Start a session

Exchange a diner token, a launch code or a guest's device id for the session every other Client API call carries.

POST/api/v1/sdk/sessionClient API

Every Client API call after this one carries the session it returns. Send one of: a diner token your backend signed, a launch code it minted, or, on a key in guest mode, this device's device id (22 or more base64url characters also brings back that device's open pickups after a restart). The session slides 12 hours from its last use, up to 7 days. conversationId is the signed-in diner's conversation that is still in progress, within 3 hours; it is always null for a guest.

Authentication

Client API. Send your publishable key (tamr_pk_live_… or tamr_pk_test_…) in x-tamr-key. The session comes back in the x-tamr-session response header, never in the body: send it on every later call.

Headers

NameTypeRequiredDescription
x-tamr-appstringNoNative apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$.

Request body

FieldTypeRequiredDescription
tokenstringNo1 to 4,096 characters.
codestringNo1 to 200 characters.
devicestringNoMatches ^[A-Za-z0-9_-]+$.
platformstringNoOne of flutter, react-native, ios, android, web.
sdkstringNoMatches ^\d{1,4}\.\d{1,4}\.\d{1,4}$.

Response

FieldTypeDescription
branchstring or nullAn address: lower-case letters, digits and dashes.
conversationIdstring or null1 to 200 characters.
localestring or nullA language tag, such as ar or en-GB.
expiresAtstring (date-time)

The x-tamr-session response header: The diner's session token: send it as x-tamr-session on every Client API call.

Example

curl -i https://tamr.link/api/v1/sdk/session \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "content-type: application/json" \
  -d '{
  "code": "lc_9f2c1b7a4e"
}'

Example response

{
  "branch": "achrafieh",
  "conversationId": "cm1conv0001",
  "locale": "ar",
  "expiresAt": "2026-10-24T08:00:00Z"
}

Errors

Every error has the same body; switch on data.code. See Errors and rate limits.

data.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
token_invalid401The diner token's signature, issuer, audience, key id or times are wrong. The message says which.
token_replayed409That token was already used. Sign a new one for each session.
code_invalid401The launch code is unknown, spent or expired. Mint a new one.
guest_not_allowed401The key has no guest mode: sign the diner in with a token or a code.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.