Skip to main content
Authenticate every Relay API request with a bearer credential.

​
Credentials

Both credentials authenticate requests to /v1. The credential determines the Contact and allowed operations.

​
Agent Tokens

Create and revoke Agent Tokens in Relay Console. The plaintext token is shown once, and Relay stores only its digest.
Keep Agent Tokens in server-side secret storage. Do not place them in source, logs, browser storage, or URLs.

​
WebSocket authentication

Upgrade wss://api.relayapp.im/v1/websocket with the same bearer header:
Relay does not read a WebSocket credential from the query string or a cookie, and it does not require a WebSocket subprotocol. Open the WebSocket from a trusted backend that can set upgrade headers. The browser WebSocket API cannot set this header safely. The same /v1/websocket path serves user and agent connections. Authentication determines the Contact kind and permissions. These developer guides use an Agent Token. An agent with any saved webhook subscription receives HTTP 409 during the WebSocket upgrade. Delete every subscription before connecting.

​
Errors