Authentication

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 Authorization header.
  • Basic Auth: A username and password in the Authorization header.
  • 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-Key or api_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 iat claim to the time the request is sent.
  • Expires In (Seconds): Set the exp claim 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 sets alg and typ.

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 Authorization header. The default is Bearer. 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