Authentication

Authorizing with OAuth 2.0

Get, refresh and send OAuth 2.0 access tokens with the authorization code or client credentials grant.

Overview

With OAuth 2.0, a request doesn't carry a fixed credential. Instead, Relay gets an access token from the API's authorization server and sends that token with each request. Relay stores the token, sends it until it expires and can refresh or replace it before sending.

Relay supports two grant types:

  • Authorization Code: You sign in to the provider in a browser sheet inside Relay, and Relay exchanges the code it returns for a token. Use it for APIs that act on behalf of a user.
  • Client Credentials: Relay asks the token endpoint for a token with the client's own ID and secret. Use it for service-to-service APIs.

The implicit and password grants aren't supported.

OAuth 2.0 is most useful set once on a workspace, collection or folder. Every request that inherits it shares the same token. For more about levels, see Inheriting authentication.

Set up the grant

Open the Auth tab, click the auth type menu and choose OAuth 2.0. Then fill in the Grant card with the details your provider gives you:

  • Grant Type: Authorization Code or Client Credentials.
  • Authorization URL: For Authorization Code, the provider's sign-in page, such as https://auth.example.com/authorize.
  • Token URL: The endpoint that issues tokens, such as https://auth.example.com/token.
  • Redirect URI: For Authorization Code, the redirect URI registered with the provider. It must match the provider's registered URI exactly.
  • Client ID: The client's identifier.
  • Client Secret: The client's secret. For Authorization Code, public clients can leave it empty.
  • Scope: The scopes to request, separated by spaces. Optional.
  • Use PKCE: For Authorization Code, add a PKCE code challenge to the sign-in. It's on by default. Most providers require it for public clients.

Every field accepts variables, so you can keep the client ID and secret in an environment, such as {{clientId}} and {{clientSecret}}.

Advanced options

Click Advanced to show the less common settings:

  • Client Authentication: How Relay sends the client ID and secret to the token endpoint: Basic Auth Header (the default) or In the Request Body.
  • Code Challenge Method: For PKCE, S256 (the default) or plain.
  • Refresh URL: Where refresh requests go. Leave it empty to use the token URL.
  • Audience and Resource: Values some providers require, sent as the audience and resource parameters.
  • State: For Authorization Code, a fixed state value. Leave it empty to have Relay generate one for each sign-in.
  • Extra Authorization Parameters: For Authorization Code, other parameters to add to the sign-in URL.
  • Extra Token Request Parameters: Other parameters to add to token requests.
  • Send the ID token instead of the access token: Send the id_token the provider returns, for APIs that expect an OpenID Connect ID token.

Get an access token

The Access Token card at the top of the form shows the current token, when it expires and its scope.

Click Get New Access Token:

  • For Client Credentials, Relay requests a token from the token URL.
  • For Authorization Code, Relay opens a sheet with the provider's sign-in page. Sign in and approve access. When the provider redirects to your redirect URI, Relay catches the redirect, closes the sheet and exchanges the code for a token. The redirect URI doesn't need to point to a running server.

To stop signing in, click Cancel. Sign-ins stay signed in between token requests, so the provider may skip its sign-in page the next time. To sign in as someone else, click the More button (…) in the sheet and choose Clear Browser Session. If the page doesn't load, the sheet shows Couldn't Load the Sign-In Page with the reason.

Once you have a token, the card offers more actions:

  • Refresh: Get a new token with the refresh token. This appears when the provider returned a refresh token.
  • Clear: Forget the token.
  • Copy Token: Copy the token's value to the clipboard.

If a request inherits OAuth 2.0, its Auth tab shows the same Access Token card above the inheritance list, so you can get a token without leaving the request.

Choose how the token is sent

The Sending card controls what goes out with each request:

  • Send Token In: Header, or Query Parameter.
  • Header Prefix: The word before the token in the Authorization header. The default is Bearer.
  • Parameter Name: For a query parameter, its name. The default is access_token.
  • Refresh expired tokens before sending: When the token has expired and there's a refresh token, refresh it before sending. It's on by default.
  • Get a token before sending when there's none: For Client Credentials, request a token automatically when there isn't one or it can't be refreshed. It's on by default.

When you send a request, Relay uses the stored token while it's valid. If the token expires within a minute, Relay refreshes or replaces it according to these settings first. For Authorization Code, a token can only come from signing in, so when there's no usable token the request isn't sent and the response inspector asks you to get one in the Auth tab.

Understand where tokens are kept

A token belongs to the level whose auth fetched it, such as the workspace, and to the grant's details: its grant type, URLs, client ID, scopes, audience and resource. Every request that inherits that level shares the token. If an environment changes one of those details, such as the client ID, Relay keeps a separate token for each environment and uses the one that matches.

Tokens are stored encrypted on your Mac. They aren't part of the workspace's files, so they aren't shared with the workspace, and getting or clearing a token isn't something you can undo.

Token requests use the same proxy and certificate settings as the level that owns the auth.

See Also