Auth

Most APIs need credentials on every call. Getman lets you set them once at the project, collection or folder level, and each request inherits them unless it says otherwise. Secret values stay in your keychain and never reach a file in Git.

How auth is inherited

A request’s auth is the first value that is not Inherit, checked in this order:

1. The request itself
2. Its folders, from the innermost to the outermost
3. The collection
4. The project

Set Access at the project level for the usual case, such as a bearer token used by every request. Override it on a folder or request only when one endpoint needs something else, such as a public login route with No auth.

To set project auth, open Project settings and choose Access.

Auth types

The Auth tab offers these types:

Type	What it sends
Inherit	Whatever the parent level sets
No auth	Nothing. Use it to switch auth off for one request
Bearer token	Authorization: Bearer <token>. You can change the prefix
API key	A key in a header or in query parameters, under the name you choose
Basic	Authorization: Basic with a username and password
OAuth 2.0	A token from an authorization server, described below
Custom headers	Headers you define, for APIs with a bespoke scheme
Cookies	Cookies you set by hand

Put secret values in a secret variable, such as {{token}}, instead of typing them into the field. Then the value stays out of exports and out of the contract.

OAuth 2.0

Choose OAuth 2.0, then pick a Grant type:

Grant type	Use it when
Client credentials	A server or script calls the API with its own identity
Password	You log in as a user with a username and password
Authorization code	A user signs in through the browser. Getman uses PKCE
Refresh token	You already have a refresh token and want a new access token

Fill in the Token URL, Client ID, Client secret, Scope and Audience where the provider needs them. For Authorization code, also set Authorize URL and Redirect URI. The redirect URI must match the one registered with the provider.

The Client secret field suggests keeping the value in a secret variable. For Client credentials, the Send client credentials setting chooses between sending them in the body and in a Basic header.

OAuth 2.0 is not exported into code snippets.

Log in automatically with a token flow

Many APIs issue a short-lived token from a login request. Getman can run that login for you and retry the failed call:

1. Open Project settings → Access.
2. Turn on Use token flow.
3. Choose the Login request. It runs to obtain a token, and its response values are stored in variables.
4. Set Extract from to the body path accessToken and Store in variable to token.
5. Set Refresh on status to the codes that should trigger a new login, such as 401, 403.

When a request gets one of those statuses, Getman runs the login again and retries once. Your requests keep using {{token}} as usual.

Use Refresh request when a separate call renews the token rather than a full login.

Variables and secrets

Variables resolve in this order, with the first match winning:

1. Runtime values set by an extractor or script during a run
2. The environment you selected
3. The collection
4. The project
5. Global variables

Secret variables are masked in the UI, and their values are removed from output. Getman stores secret values in your system keychain, under the service dev.getman.app, with the user master-key for the encryption key. If the keychain is not available, Getman falls back to a master.key file.

To fill secrets in the app, open Environments, choose the environment, and type each value. They are never written to the environments/*.yaml files in the team workspace, which keep the variable names with blank values.

Secrets for the command line and agents

The command line and coding agents take secret values from environment variables named GETMAN_VAR_<KEY>, where <KEY> is the variable name:

export GETMAN_VAR_password="your-demo-password"
getman run "Shop API" --workspace getman --env Local

Set the variables in the shell that starts the agent or the CI job. Getman scrubs the values from its output.

Check auth

1. Send a request that needs auth. A 401 means the credential is missing or wrong.
2. Open the response Tests tab and add a status assertion if you expect a 401 for a negative case. See Testing.
3. For a token flow, send a request after the token expires and check that Getman logs in again.

If a request still fails, Troubleshooting lists the usual causes.