Skip to main content

User tokens

A user token is a short-lived signed credential bound to an application, customer account, and recipient. It enables frontend access without exposing the backend's application API key.

Issue a token​

Your backend must first validate its own user session and active organization membership. It then calls the endpoint with an application key containing users:token_issue.

POST /v1/user-tokens
Authorization: Bearer APPLICATION_API_KEY
Content-Type: application/json
{
  "account_key": "org-123",
  "recipient_external_id": "user-42",
  "ttl_seconds": 900
}

The recipient ID must match recipient.external_user_id in notification requests. Notify creates or resolves the recipient identity, so requesting a token does not require a prior notification.

The response contains access_token, token_type, and expires_at. Lifetime defaults to 900 seconds and must be between 60 and 3600 seconds.

Use it in your frontend​

const response = await fetch(notifyApiUrl + '/v1/user/inbox', {
  headers: {Authorization: 'Bearer ' + accessToken},
});
if (!response.ok) throw new Error('Unable to load inbox');
const {data} = await response.json();

The frontend does not supply another recipient header to switch identity. Notify takes the recipient and account from the signed token.

Refresh and organization switching​

Request a new token through your authenticated backend before expiration. When the active organization changes, discard the old token and request one for the newly authorized account. Close the old SSE connection and clear cached inbox data.

Do not accept arbitrary account or recipient identifiers from the browser without checking them against your session. Notify trusts the backend issuing the token to choose an authorized identity.

The token's four current scopes are fixed by Notify; see User-token scopes.