# 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.

Source: https://tamr.link/docs/api/start-session

`POST https://tamr.link/api/v1/sdk/session`

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

| 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:

```bash
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"
}'
```

Node:

```js
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);
```

Python:

```python
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

```json
{
  "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](https://tamr.link/docs/errors).

| `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. |
