Tenancy & relay_user_id

Both relays rest on one shared multi-tenant model. Learn it here once; it applies identically to the Auth Relay and the Chat Relay.

What is a tenant?

A tenant is an application or backend that consumes a relay. When you integrate a relay, your service becomes a tenant: you receive an identity and secrets, and every call is attributed to your tenant.

Both relays share one common tenants collection: the same identity fields, the same lifecycle, the same credential conventions. That is what lets you learn the integration once.

Tenant credentials

Provisioning a tenant returns its secrets once:

Credential	Role	Relay
tenant_id	Public tenant identifier (header on every signed call).	Auth + Chat
tenant_secret	HMAC signing secret (never expose client-side).	Auth + Chat
widget_public_key	Public web-widget key, safe to expose in the browser.	Chat only

Secrets are shown only once

tenant_secret (and widget_public_key for the Chat Relay) is returned only at provisioning time. Store it immediately in a secrets vault. If lost, rotate it — see Tenant lifecycle.

relay_user_id — the universal validator

A relay does not store your passwords and does not “own” your users. Instead, it links your user identifier (backend_user_id) to a relay-side identity. That link is the relay_user_id: the universal validator that follows the “Stripe Connect” model.

1. Your backend presents one of its users to the relay (during pairing on the Auth Relay, or operator provisioning on the Chat Relay).
2. The relay establishes a stable link between your backend_user_id and its internal identity.
3. Subsequent operations (approval push, sudo step-up, operator token…) target that link, never a shared global account.

A single real user can therefore be linked to multiple tenants and multiple backends at once, with each link kept isolated.

Cross-tenant isolation

Isolation is a first-class guarantee:

• Chat Relay — an operator token is issued with a tids: { tenant_id: role } scope limited to the calling tenant. Tenant A cannot forge a token that opens tenant B’s inbox.
• Auth Relay — pairings and challenges are bound to the tenant that created them; one tenant never sees another’s devices.

Because the caller is already authenticated by HMAC, the relay reliably knows its tenant_id before applying that scope.

Note

Targeting lists (for example relay_user_linked_id_list and relay_group_linked_id_list for Auth Relay sudo step-up) reference these per-tenant links. See Sudo (step-up).

Next steps

• Authentication (HMAC) — sign your calls.
• Tenant lifecycle — provision and rotate secrets.