Diner identity: sign diner tokens for the Tamr SDK

Sign a short EdDSA JWT on your backend to tell Tamr's AI waiter which of your users is chatting, in Node, Kotlin, Dart or Swift, or mint a one-time launch code instead.

Your app tells the waiter who the diner is by asking your backend for a short signed token, each time the waiter page needs one. Your backend checks its own user is logged in, then signs a JWT with an Ed25519 key. If your backend can't sign tokens, it can mint a one-time launch code instead.

The identity provider

The controller calls your identity provider whenever the page needs a fresh token, with a reason (first_open, expired or refused), and expects an answer within 15 seconds:

PlatformA signed-in dinerA launch codeNo one
Web, React Native{ token }{ code }null
FlutterTamrToken(token)TamrLaunchCode(code)null
iOS.token(token).code(code)nil
AndroidTamrIdentity.token(token)TamrIdentity.code(code)null

Ask your backend for a fresh token every time: a token works once. The page handles renewal, retries and expiry itself.

1. Make a key pair, once

Generate an Ed25519 key pair with your platform's crypto library (in Node, generateKeyPairSync("ed25519") from node:crypto) and keep the private key on your server, as a secret.

2. Register the public half

In Settings > App keys, open the app key, and under Diner token signing keys add the public key as a JWK ({"kty":"OKP","crv":"Ed25519","x":"…"}) with a name and a kid you choose: letters, digits, dots, dashes and underscores. The dashboard refuses a private key. The same section shows the exact iss and aud values to sign with.

3. Sign each token

ClaimValue
header algEdDSA
header kidThe kid you registered
issThe app key's id, as shown under Diner token signing keys (not the tamr_pk_… key itself). It stays the same when the key is rotated.
audtamr: and the restaurant address, for example tamr:your-restaurant
subYour own id for the user. Never a name, email or phone number.
iat, expIssued and expiry times in seconds, at most 5 minutes apart. Tamr allows 60 seconds of clock difference.
jtiA random id. Each token is accepted once.
branchOptional: a branch address, as a hint
localeOptional: a language tag, as a hint

The same function in the four languages backends behind these apps are written in. The Node one runs in Tamr's tests against Tamr's own token check.

// Signs a diner token for Tamr's waiter on your backend (Node 18+, no packages).
// Your app asks your backend for one whenever the waiter needs it (setIdentityProvider).
import { createPrivateKey, randomUUID, sign } from "node:crypto";

export function signTamrDinerToken({
	privateKeyPem,
	kid,
	appKeyId,
	restaurant,
	userId,
}) {
	const now = Math.floor(Date.now() / 1000);
	const header = { alg: "EdDSA", typ: "JWT", kid };
	const claims = {
		iss: appKeyId, // the app key's id (Settings, App keys)
		aud: `tamr:${restaurant}`,
		sub: userId, // your own id for this diner: never a name, email or phone
		iat: now,
		exp: now + 120, // at most 5 minutes
		jti: randomUUID(), // used once
	};
	const encode = (part) =>
		Buffer.from(JSON.stringify(part)).toString("base64url");
	const input = `${encode(header)}.${encode(claims)}`;
	const signature = sign(
		null,
		Buffer.from(input),
		createPrivateKey(privateKeyPem),
	);
	return `${input}.${signature.toString("base64url")}`;
}

A token is spent when the page uses it, so sign a new one on every request from the app. The errors you may see are token_invalid (signature, iss, aud, kid or times wrong; the message says which) and token_replayed (the token was used before).

Launch codes

If your backend can't sign tokens, mint a one-time code with a secret API key that has the diner:sdk permission: Create a launch code. A code lasts 5 minutes and works once; your app returns it from the identity provider as a code. branch and locale are optional in the request, and an unknown branch is refused.

Rotating keys

Add a second signing key, move your backend to it, then revoke the old one. Rotating the app key itself, with 0, 7 or 30 days' grace, doesn't change what you sign.

One restaurant, one set of users

Tamr knows a diner by the restaurant and your user id, not by the app key: every app key of a restaurant shares the same users, so user 123 from its iOS app and its website is one diner with one history. A restaurant whose apps keep separate user lists must give its ids distinct prefixes (for example ios:123 and web:123).

When the diner signs out

Call clearIdentity() and dispose of the controller, then make a new one for the next diner. With a key in guest mode, clearIdentity() also ends the guest and starts a new one at once, on a new device id, so the next person on a shared phone never sees the last one's conversation. An app that draws its own chat calls End a session, which also ends the diner's current conversation, so their next sign-in starts afresh on every device.