Authentication

Inheriting authentication

Set authentication once on a workspace, collection or folder and let requests inherit it.

Overview

Most APIs authenticate every request the same way. Instead of adding the same token to each request, you set authentication on the level that holds them, and the requests below inherit it.

Relay looks for authentication at five levels, from the most specific to the least:

  1. The request.
  2. The request's folders, starting with the innermost.
  3. The request's collection.
  4. The workspace.
  5. Globals, which apply to every workspace.

The first level that sets its own authentication decides how the request is sent. A level that inherits passes the decision up to the next one. New requests, folders, collections and workspaces all inherit, and globals start with No Auth, so a request is sent without authentication until some level sets it.

Drafts aren't in a collection, so they skip the folder and collection levels and inherit from the workspace and globals.

Choose how a level is authenticated

Each level has the same auth type menu at the top of its Auth tab. Choose one of these:

  • Inherit from Parent: Use the authentication of the level above. Requests, folders and collections offer this option.
  • Inherit from Global Settings: Use the global authentication. Workspaces offer this option.
  • No Auth: Send requests without authentication. This also turns authentication off for every level below that inherits.
  • An auth type: Send requests with Bearer Token, Basic Auth, API Key, OAuth 2.0, OAuth 1.0, JWT Bearer, Digest Auth, NTLM, AWS Signature or Hawk, and fill in its settings.

Globals have nothing to inherit from, so their menu has no inherit option.

When you switch to another type and back, Relay restores the settings you entered for that type while the tab stays open. Each change of type is a single step you can undo.

Set authentication on each level

  • Request: In the request editor, click Auth, or press Command-3.
  • Collection or folder: In the sidebar, Control-click the collection or folder and choose Edit Auth…. The Collection Settings window opens to its Auth tab.
  • Workspace: In the sidebar, click the workspace menu and choose Edit Workspaces…. Select the workspace, then click Auth.
  • Globals: In the Workspaces window, select Globals, then click Auth.

See where a request's authentication comes from

When a request inherits, its Auth tab shows "Inheriting" followed by the auth type and the level it comes from, such as Inheriting Bearer Token from Payments API. Below it, the tab lists each level the request inherits through, from Global Authentication down to This Request, with a checkmark on the level that decides.

To change the inherited authentication, click Edit on the checked level. Relay opens the Collection Settings window for a collection or folder, or the Workspaces window for a workspace or globals.

Folders, collections and workspaces show the same list in their own Auth tabs, so you can check what they pass down.

Override the authentication you inherit

A header you add in a request's Headers tab takes precedence over a header with the same name that authentication adds. For example, an Authorization header in the Headers tab replaces the one a Bearer Token level would send, and Relay doesn't add an AWS, OAuth 1.0 or Hawk signature or answer a Digest challenge on top of it. In the same way, an enabled query parameter takes precedence over an auth parameter with the same name.

To send a single request without authentication, choose No Auth for that request.

Keep credentials out of shared files

Every field in an auth form accepts variables, such as {{apiToken}}. Relay resolves them with the request's variables and its active environment each time it sends, so one auth setting on a workspace can use different credentials in each environment.

Relay doesn't write the tokens, passwords, secrets and keys you type into auth forms to a workspace's files. They stay on your Mac, so sharing a workspace folder doesn't share them. A field that holds only variable references, such as {{apiToken}}, is written as is. To learn how values stay on your Mac, see Keeping secrets on your Mac.

Note

If a workspace contains an auth type from a newer version of Relay, the Auth tab shows Unsupported Authentication. Relay keeps the setting but doesn't send it, so requests that use that level go out without authentication.

See Also