Skip to main content
An access token is a short-lived credential that your backend mints (issues) from your API key and passes to a browser or mobile client. The client sends the token to Relay, so the API key never leaves your server. Each token expires after 15 minutes. Use the table below to choose between an access token and the other ways to call Relay from a client.

Requirements

  1. An App with elevated rate limits — Only Apps with elevated rate limits can mint tokens. Request them through the support widget in the Relay Dashboard.
  2. A token endpoint on your backend — This endpoint holds the API key, mints tokens, and returns them to your client.

How to use it?

The flow has four steps:
  1. Your backend sends your API key to POST /access-tokens.
  2. Your backend returns the token to the client.
  3. The client sends the token in the Authorization header on supported Relay endpoints.
  4. When the token expires, the client requests a new token from your backend.

Mint a token on your backend

Send your API key in the x-api-key header with an empty JSON body.
The response has four fields: The response has Cache-Control: no-store. Do not cache it.

Call Relay from the client

Send the token in the Authorization header over HTTPS.
Send an API key or a token in a request, not both. Relay rejects a request that has both.

What a token can do

Make requests that use fee sponsorship or fixed rates from your backend with your API key. Enforce your sponsorship rules there. With a token, request history returns public data only. It does not include the integrator-level read access that an API key can have.

Rate limits

Relay counts token requests for each API key and client IP address. All tokens from the same API key and the same IP share one allowance. More tokens do not increase it. Different IP addresses and different API keys have separate allowances. Minting is limited to 600 requests per minute for each API key. Failed mint attempts count toward that limit. When a limit is reached, Relay returns 429 with the error code RATE_LIMITED. See Handling Rate Limits for how to recover.

Token lifecycle

Errors

The API also calls a token an API session, for example in the error code INVALID_API_SESSION.

Caveats

  • A token works from any origin and IP address, because Relay checks the App’s IP and origin restrictions only on the mint request. Restrict your App to your backend’s IP addresses.
  • Protect your token endpoint against automated abuse. Anyone who can call it can get a token, so authenticate or throttle it.