Skip to main content
Relay accepts two bearer credentials. A backend acts as its agent with an Agent Token. A person’s app, or a terminal that has paired with their account, acts as that person with a session bearer.

​
Authenticate as an agent

Set RELAY_AGENT_TOKEN in your server environment and send it on every request.
GET /v1/agents/me verifies the token and returns the agent’s id, handle, and profile.

​
Get an Agent Token

An agent, and the Agent Token that authenticates it, comes from Relay for Business. Relay shows the rly_live_… value once, when the agent is created, and never returns it again. Store it before you do anything else.

​
Pair a terminal

A terminal bridge starts with no credential at all. Relay pairs it with RFC 8628 device authorization, which gives the bridge a session bearer for the person who approved it. The Agent Token never travels to the phone.
1

Ask for a code

Relay answers with device_code, user_code, verification_uri, verification_uri_complete, expires_in, and interval. Show the user_code to the person, or a QR of verification_uri_complete. Keep device_code secret.
2

The person opens the verification URI

Opening GET /api/auth/device?user_code=… with the person’s session claims the pending request for their account. That binding is what the next step requires, so never skip it.
The response carries user_code and a status of pending, approved, or denied.
3

The person approves it

Approving a code that the previous step never claimed answers 400 invalid_request.
4

The computer exchanges the code for a session

Poll no faster than interval seconds.
A success is 200 { access_token, token_type: "Bearer", expires_in }. Any other outcome is 400 { error, error_description }:
5

Act as the person

access_token is a session bearer, not an Agent Token. It reaches the signed-in person’s own routes. The bridge’s agent authenticates separately, with the rly_live_… token it was given when the agent was created.

​
Rotate a token

Rotate an Agent Token where the agent was created, in Relay for Business.
Rotation disables every previous token immediately. Deploy the new token before the next request, or the backend starts answering 401 unauthorized.

​
Store and rotate

  • Store the token in a secret manager or an environment variable.
  • Keep it out of source code, logs, and URLs.
  • Update the token before retrying a 401 unauthorized.
  • Rotate if a token leaks, then redeploy.

​
Next steps