OAuth 2.0

Grant Types

API Studio supports two OAuth 2.0 grant types:

Authorization Code

For user-facing apps. Redirects the user to a login page, captures an authorization code, and exchanges it for tokens. Best for APIs that require user consent.

Client Credentials

For machine-to-machine communication. POSTs client ID and secret directly to the token endpoint. No user interaction required. Best for service accounts and backend integrations.

Configuration

Select OAuth 2.0 from the Auth type dropdown. The following fields are available:

Field	Description
Grant Type	`authorization_code` or `client_credentials`
Auth URL	Authorization endpoint (Authorization Code only)
Token URL	Token endpoint — where codes/credentials are exchanged for tokens
Client ID	OAuth application identifier
Client Secret	OAuth application secret — required for Client Credentials, optional for Authorization Code (public clients use PKCE instead)
Scope	Space-separated scopes (e.g. `read write profile`)
Access Token	Pre-obtained token — paste here to skip the OAuth flow
Refresh Token	Used to obtain a new access token when the current one expires
Token Type	Token type returned by server (usually `bearer`)
Expires At	Token expiration timestamp
Token Prefix	Prefix for the Authorization header (default: `Bearer`)
Additional Params	Extra key-value pairs sent with the token request (max 20). Keys and values support `{{variables}}`; standard OAuth2 parameter names (`grant_type`, `client_id`, …) are ignored and cannot be overridden

Authorization Code Flow

The standard flow for user-facing applications:

1

Click Get Token — API Studio opens a browser window to the authUrl

2

User logs in and grants permission — the provider redirects back with an authorization code

3

API Studio captures the code and exchanges it at the tokenUrl (POST with client ID, code, redirect URI, and PKCE code_verifier; the client secret is included only if set)

4

The returned access token is stored and used in the Authorization header for subsequent requests

Example configuration:

Grant Type:    Authorization Code
Auth URL:      https://accounts.google.com/o/oauth2/v2/auth
Token URL:     https://oauth2.googleapis.com/token
Client ID:     {{google_client_id}}
Client Secret: {{google_client_secret}}
Scope:         openid email profile

PKCE: API Studio always attaches PKCE (S256 code_challenge) to the authorization request and sends the code_verifier during the code exchange, as required for native apps by RFC 8252. Because of PKCE, the Client Secret is optional for this grant — leave it empty for public clients.

Redirect URI: the local callback listens on http://127.0.0.1:<random port>/callback. Register a loopback redirect URI with your provider; most providers accept loopback URIs with any port.

Timeout & cancel: the flow waits up to 2 minutes for the browser callback. Use the Cancel button next to Get Token to abort an in-progress flow.

Client Credentials Flow

The simplest flow — no user interaction, no browser redirect. Ideal for service-to-service authentication:

1

Click Get Token — API Studio POSTs client_id + client_secret directly to the tokenUrl

2

The token endpoint validates the credentials and returns an access token

3

The token is stored and sent as Authorization: Bearer <token>

Example configuration:

Grant Type:    Client Credentials
Token URL:     https://auth.example.com/oauth/token
Client ID:     {{service_client_id}}
Client Secret: {{service_client_secret}}
Scope:         api:read api:write

Token Refresh

When the token endpoint returns a refresh_token, API Studio can renew the access token without repeating the full flow:

Manual: the Refresh button (enabled once a refresh token is stored) sends a grant_type=refresh_token request to the Token URL — no browser round-trip, even for Authorization Code configs.
Automatic: before sending a request, if the stored token is expired or expires within 30 seconds and a refresh token exists, API Studio silently refreshes it first. If the refresh fails, the request proceeds with the existing token.
Rotation: if the server returns a new refresh token it replaces the stored one; if it omits it, the existing refresh token is kept.

The editor shows a live expiry indicator next to the access token (Expires in 45 minutes / Expired 5 minutes ago).

No expires_in? Some providers (e.g. GitHub) don't return an expiry. Those tokens are treated as non-expiring: no expiry indicator is shown and auto-refresh never triggers. Numeric-string values like "3600" are parsed normally.

Token Storage

Fetched tokens are saved to the entity that owns the OAuth 2.0 configuration, so every request sharing that config picks them up:

Request-level auth — the token is stored on the request itself.
Inherited auth — the token is stored on the folder or collection providing the config. The editor shows “Token will be saved to: <name>” so it's clear where it lands.
Collection / folder editors — fetching a token from the Auth tab of a collection or folder stores it on that collection or folder.

Tokens never create or overwrite auth on entities that don't already use OAuth 2.0.

Token Field

If you already have an access token (from another tool, a login script, or copied from a browser session), paste it directly into the Access Token field. API Studio will use it without executing any OAuth flow.

Access Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

→ Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token prefix

The Token Prefix field controls the scheme name before the token in the Authorization header:

Prefix value	Resulting header
Bearer (default)	Authorization: Bearer <token>
MAC	Authorization: MAC <token>
Custom string	Authorization: <custom> <token>
(empty)	Authorization: <token>

Variable Support

All OAuth 2.0 configuration fields support {{variable}} placeholders — resolved from environments, vault secrets, or collection variables.

Auth URL:      {{oauth_auth_url}}
Token URL:     {{oauth_token_url}}
Client ID:     {{oauth_client_id}}
Client Secret: {{oauth_client_secret}}
Scope:         {{oauth_scopes}}
Access Token:  {{current_access_token}}

This is especially useful for managing multiple environments (dev, staging, production) with different OAuth providers or client applications.

Tip: Store clientSecret in the encrypted vault rather than in environment variables. Use a Secret Set to map the vault key to a {{variable}} — the secret is automatically scrubbed from history and session files.

Security Note

Auth credentials appear in multiple places:

Actual Request tab — shows resolved auth headers with real values
Code Export — generated code includes resolved auth values
History — saved request headers contain injected auth (scrubbed only if from vault)
collections.json — auth config saved in plain text (committed to git)
Access & refresh tokens — tokens fetched via Get Token / Refresh are persisted in plain text alongside the auth config in collections.json. Anyone with the file (or the git repo it's committed to) can use them until they expire — treat exported or shared collections accordingly

Recommendation: Store sensitive credentials in the Secret Vault and reference them as {{variables}}. Vault secrets are automatically scrubbed from persisted history, and the vault file is AES-256-GCM encrypted — safe to have alongside git-tracked files.