Requirements
- 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.
- 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:- Your backend sends your API key to
POST /access-tokens. - Your backend returns the token to the client.
- The client sends the token in the
Authorizationheader on supported Relay endpoints. - When the token expires, the client requests a new token from your backend.
Mint a token on your backend
Send your API key in thex-api-key header with an empty JSON body.
The response has
Cache-Control: no-store. Do not cache it.
Call Relay from the client
Send the token in theAuthorization header over HTTPS.
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 codeINVALID_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.