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.
/api/v1/sdk/sessionClient APIEvery 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
| Name | Type | Required | Description |
|---|---|---|---|
x-tamr-app | string | No | Native 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
| Field | Type | Required | Description |
|---|---|---|---|
token | string | No | 1 to 4,096 characters. |
code | string | No | 1 to 200 characters. |
device | string | No | Matches ^[A-Za-z0-9_-]+$. |
platform | string | No | One of flutter, react-native, ios, android, web. |
sdk | string | No | Matches ^\d{1,4}\.\d{1,4}\.\d{1,4}$. |
Response
| Field | Type | Description |
|---|---|---|
branch | string or null | An address: lower-case letters, digits and dashes. |
conversationId | string or null | 1 to 200 characters. |
locale | string or null | A language tag, such as ar or en-GB. |
expiresAt | string (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"
}'import { createClient } from "@tamr/api";
const tamr = createClient({ appKey: process.env.TAMR_APP_KEY });
// The session is kept by the client and sent with every later call.
const session = await tamr.startSession({ code: "lc_9f2c1b7a4e" });
console.log(session);import os
import requests
API = "https://tamr.link/api/v1"
headers = {"x-tamr-key": os.environ["TAMR_APP_KEY"]}
response = requests.post(
f"{API}/sdk/session",
headers=headers,
json={"code": "lc_9f2c1b7a4e"},
timeout=30,
)
response.raise_for_status()
# The session comes back in a header, never in the body.
session = response.headers["x-tamr-session"]
print(response.json())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.code | Status | What to do |
|---|---|---|
app_key_invalid | 401 | The key is wrong, revoked or of another kind. Check it in the dashboard. |
sdk_disabled | 403 | The SDK isn't switched on for this restaurant. Ask Tamr. |
origin_not_allowed | 403 | A browser called from an origin the key doesn't list. Add the origin to the key. |
token_invalid | 401 | The diner token's signature, issuer, audience, key id or times are wrong. The message says which. |
token_replayed | 409 | That token was already used. Sign a new one for each session. |
code_invalid | 401 | The launch code is unknown, spent or expired. Mint a new one. |
guest_not_allowed | 401 | The key has no guest mode: sign the diner in with a token or a code. |
invalid_request | 400 | A field doesn't match the spec. The message says which. |
rate_limited | 429 | Wait retryAfter seconds (also in the Retry-After header), then try again. |