> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requestly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OAuth 2.0
> Acquire and attach OAuth 2.0 tokens across all six standard grant types, with built-in token caching and refresh.
OAuth 2.0 is the dominant authorization framework for modern APIs. Requestly handles the entire flow: it opens the provider's consent screen when needed, exchanges the response for an access token, caches the token, refreshes it before it expires, and attaches it to every request.
You pick a **grant type** that matches how the API issues tokens; Requestly shows the right fields for the grant you choose.
## Choose OAuth 2.0 as the auth type
Open any request or collection, then go to the **Authorization** tab.
Pick **OAuth 2.0** from the **Authorization type** dropdown.
Use the **Grant type** dropdown at the top of the OAuth 2.0 form. Requestly swaps the field set to match. See [Grant types](#grant-types) below for which to pick.
The **Get token** button at the bottom of the form is enabled once all required fields are filled. Requestly runs the flow (opening the browser for grants that need user consent), stores the resulting token, and shows its status.
Click **Send**. Requestly attaches the cached token as `Authorization: Bearer ` (the prefix is configurable - see [Token settings](#token-settings) below).
## Grant types
Pick the grant that matches how the API issues tokens. If you are unsure, the provider's documentation will tell you.
| Grant type | When to use |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization code** | Server-to-server apps where the API has a confidential client secret. Most common for first-party integrations. |
| **Authorization code (PKCE)** | Public clients (mobile, SPA, CLI) where you cannot keep a client secret. Adds a code challenge for binding the auth request to the token exchange. |
| **Client credentials** | Service-to-service calls with no user involved. Authenticates the application itself. |
| **Implicit** | Legacy browser-only flow. New integrations should use PKCE instead. Still required by a handful of older providers. |
| **Password credentials** | Resource owner password grant. Only use with first-party apps where you control both ends and only when no other grant fits. |
| **Manual token** | Paste an access token you obtained elsewhere. Useful for one-off testing or when the provider does not implement any standard grant. |
### Authorization code
The standard three-legged flow. Requestly opens the provider's authorization page, the user signs in and consents, the provider redirects back with a code, and Requestly exchanges the code for a token at the token endpoint.
| Field | Required | Purpose |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| **Auth URL** | Yes | Provider's authorization endpoint, e.g. `https://provider.example.com/oauth/authorize`. |
| **Token URL** | Yes | Provider's token endpoint, e.g. `https://provider.example.com/oauth/token`. |
| **Callback URL** | Yes | Redirect URI registered with the provider. See [Callback mode](#callback-mode-hosted-vs-embedded) below. |
| **Client ID** | Yes | OAuth client identifier issued by the provider. |
| **Client Secret** | Yes | OAuth client secret. Store in the [vault](../../vault/vault) rather than pasting it inline. |
| **Scope** | Optional | Space-separated scopes you are requesting, for example `read:user write:user`. |
| **State** | Optional | CSRF nonce. Requestly verifies it on the callback when set. |
### Authorization code (PKCE)
Same as Authorization code, plus a code-challenge / code-verifier pair. Requestly generates and tracks both for you.
Additional field:
| Field | Required | Purpose |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Challenge method** | Yes | `SHA-256` (recommended) or `Plain`. SHA-256 is what RFC 7636 mandates for confidentiality; `Plain` exists only for legacy providers. |
The **Client Secret** field is optional for PKCE - public clients omit it.
### Client credentials
Two-legged flow. No user, no browser.
| Field | Required | Purpose |
| ----------------- | -------- | -------------------------- |
| **Token URL** | Yes | Provider's token endpoint. |
| **Client ID** | Yes | OAuth client identifier. |
| **Client Secret** | Yes | OAuth client secret. |
| **Scope** | Optional | Space-separated scopes. |
### Implicit
The provider returns the token directly in the redirect URL fragment. Avoid in new integrations.
| Field | Required | Purpose |
| ---------------- | -------- | ------------------------------------------ |
| **Auth URL** | Yes | Provider's authorization endpoint. |
| **Callback URL** | Yes | Redirect URI registered with the provider. |
| **Client ID** | Yes | OAuth client identifier. |
| **Scope** | Optional | Space-separated scopes. |
| **State** | Optional | CSRF nonce. |
### Password credentials
The user's username and password are exchanged directly at the token endpoint. Use only when you trust the client with the user's password.
| Field | Required | Purpose |
| ----------------- | -------- | ------------------------------------------------------------------- |
| **Token URL** | Yes | Provider's token endpoint. |
| **Client ID** | Yes | OAuth client identifier. |
| **Client Secret** | Optional | OAuth client secret, when the provider expects one. |
| **Username** | Yes | Resource owner's username. |
| **Password** | Yes | Resource owner's password. Store in the [vault](../../vault/vault). |
| **Scope** | Optional | Space-separated scopes. |
### Manual token
For when you already have an access token from somewhere else and just want Requestly to attach it. No flow, no refresh.
| Field | Required | Purpose |
| --------- | -------- | ------------------------------------------------------ |
| **Token** | Yes | The token to attach. Click **Save token** to store it. |
## Callback mode (hosted vs. embedded)
Grants that involve a browser redirect (Authorization code, Authorization code with PKCE, Implicit) expose a **Use embedded browser** toggle.
* **Hosted callback** (default): the OAuth handshake happens in your system browser, with Requestly's hosted callback URL (`https://oauth.requestly.com/callback`) catching the redirect and handing the code back to the app. The **Callback URL** field is auto-populated and read-only.
Use this when you can register `https://oauth.requestly.com/callback` (or the staging equivalent) with the provider.
* **Embedded browser**: the OAuth handshake happens inside an in-app browser window. The **Callback URL** field becomes editable - set it to any redirect URI you have already registered with the provider. The URL is never fetched; Requestly intercepts the navigation as soon as the provider redirects to it.
Use this when the provider restricts redirect URIs to URLs you control.
Some enterprise identity providers detect embedded webviews and refuse to load the consent page (commonly seen with strict conditional-access, advanced-protection, or anti-phishing policies). When that happens, switch back to **Hosted callback** and register Requestly's callback URL with the provider.
Whichever mode you pick, the redirect URI shown in the **Callback URL** field must be listed in your OAuth app's allowed redirect URIs on the provider side. Most "invalid redirect URI" errors during the consent flow come from forgetting this step. Register the URL once in the provider's developer console before clicking **Get token**.
## Token settings
These cross-grant fields appear below the grant-specific fields (everywhere except **Manual token**).
### Header prefix
The scheme Requestly puts in front of the token in the `Authorization` header. Defaults to `Bearer`, which is what almost every provider expects. Override only if the provider documents a different prefix (for example `Token` or an empty string).
### Token selection
For providers that return both an access token and an OpenID Connect ID token in the same response. Pick which one to attach to outgoing requests:
* **Access token** (default): the standard OAuth 2.0 access token.
* **ID token**: the OIDC ID token. Pick this when you are calling an endpoint that authenticates the user identity rather than authorizing API access.
### Custom auth, token, and refresh parameters
Three collapsible tables for additional parameters most providers do not need:
* **Custom auth parameters**: extra query parameters appended to the authorization URL. Use for vendor-specific extensions like `audience`, `prompt`, or `login_hint`.
* **Custom token parameters**: extra form fields appended to the token-exchange request body.
* **Custom refresh parameters**: extra form fields appended to refresh-token requests.
Each row has a name, a value, and an enable toggle. Disabled rows are kept in the configuration but skipped at send time.
## Token lifecycle
Once you click **Get token**, the panel at the bottom of the form shows the token's status. The panel updates without you having to refresh the form.
| Status | What it means |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **No token acquired yet** | The flow has not been run yet. Click **Get token**. |
| **Acquiring token…** | The flow is running. Cancel it, or click **Restart** to start over. |
| **Bearer** badge with countdown | A valid token is cached. The countdown shows time until expiry. Click **Clear token** to invalidate it. |
| **Token expired** | The cached token's lifetime is up and there is no refresh token. Click **Get token** to start a new flow. |
| **Refreshing token…** | The cached token expired but a refresh token is available; Requestly is exchanging it for a fresh access token. |
| **Failed** with detail | The flow failed - the panel shows the headline and detail from the provider. Click **Retry** to run it again. |
Tokens are cached per authorization configuration. If you change a field that affects the token (Client ID, Auth URL, Scope, etc.), clear the existing token first to avoid stale cache hits.
### How refreshes happen
Requestly refreshes tokens **lazily, at send time**. There is no background timer that pre-refreshes before expiry. Instead:
* When you click **Send** and the cached token is still valid, Requestly attaches it as-is.
* When the cached token has expired and the provider returned a refresh token, Requestly exchanges the refresh token for a new access token before sending the request. Concurrent sends share a single refresh, so you do not end up with parallel refresh calls hitting the provider.
* When the cached token has expired and there is no refresh token, the request fails with a refresh error and the panel switches back to **Token expired**. Click **Get token** to run the grant flow again.
To force a fresh token before expiry (for example, after rotating client credentials on the provider side), click **Clear token** and then **Get token**.
The **Custom refresh parameters** table under [Token settings](#custom-auth-token-and-refresh-parameters) appends extra fields to the refresh request body when your provider needs them (some providers expect a repeated `scope` or `audience` parameter on refresh).
## Variables and the vault
All OAuth 2.0 fields accept Requestly [variables](../../environments-and-variables) and [vault](../../vault/vault) references. For long-lived credentials (client secrets, RSA keys, user passwords), store the value once in the vault and reference it by name in the form. The reference is what gets exported when you share a collection; the underlying secret stays on your machine.
## What's Next?
Sign requests with the older signature-based OAuth scheme.
Store OAuth client secrets and passwords securely.
Reference OAuth credentials by name across requests.