Authorizing with tokens and keys
Send a bearer token, username and password, API key or signed JWT with each request.
Overview
Many APIs authenticate with a credential that goes in a header or query parameter of every request. Relay offers four auth types for this:
- Bearer Token: A token in the
Authorizationheader. - Basic Auth: A username and password in the
Authorizationheader. - API Key: A key in a header or query parameter you name.
- JWT Bearer: A JSON Web Token that Relay signs each time it sends the request.
To choose one, open the Auth tab of a request, folder, collection or workspace, click the auth type menu and choose the type. To set it once for many requests, see Inheriting authentication.
Every field accepts variables, such as {{apiToken}}. Fields that hold credentials, such as Password, have an eye button that shows or hides their value.
Send a bearer token
Choose Bearer Token and enter the token in the Token field. Relay sends it as:
Authorization: Bearer <token>Send a username and password
Choose Basic Auth and enter a Username and Password. Relay joins them with a colon, encodes them in Base64 and sends the result:
Authorization: Basic dXNlcjpwYXNzd29yZA==Send an API key
Choose API Key, then fill in the form:
- Send In: Header, or Query Parameter.
- Header Name or Parameter Name: The name the API expects, such as
X-API-Keyorapi_key. - Value: The key.
Relay adds the key to each request as a header or as a parameter in the URL's query. If the name is empty, Relay doesn't send the key.
Sign and send a JWT
Choose JWT Bearer to have Relay build and sign a JSON Web Token each time it sends the request. The form has three cards.
Signing
- Algorithm: HS256, HS384 or HS512 to sign with a shared secret; RS256, RS384, RS512, PS256, PS384 or PS512 to sign with an RSA key; ES256, ES384 or ES512 to sign with an EC key.
- Secret: For HS algorithms, the shared secret. Turn on Secret is base64 encoded when the secret is Base64 for raw key bytes rather than text.
- Private Key: For the other algorithms, the key in PEM format, including its
-----BEGIN … KEY-----line. The key can't be protected with a passphrase.
Token
- Payload: The token's claims, as a JSON object. Variables in the payload are resolved before Relay signs it.
- Add issued-at time (iat): Set the
iatclaim to the time the request is sent. - Expires In (Seconds): Set the
expclaim to this many seconds after the time the request is sent. Leave it empty for a token without an expiry. - Extra Header Fields: Fields to add to the token's header, as a JSON object, such as
{"kid": "key-1"}. Relay setsalgandtyp.
For example, this payload produces a token for one user that's signed afresh for each request:
{
"sub": "{{userId}}",
"aud": "https://api.example.com"
}Sending
- Send In: Header, or Query Parameter.
- Header Prefix: The word before the token in the
Authorizationheader. The default isBearer. Leave it empty to send the token on its own. - Parameter Name: For a query parameter, its name. The default is
token.
If Relay can't build the token, such as when the payload isn't a JSON object or the key can't be read, the request isn't sent and the response inspector shows the reason.
See Also
- Inheriting authentication: Set authentication once on a workspace, collection or folder and let requests inherit it.
- Authorizing with OAuth 2.0: Get, refresh and send OAuth 2.0 access tokens with the authorization code or client credentials grant.
- Keeping secrets on your Mac: Keep tokens and passwords out of shared workspace files.