Authorization Code Grant

The authorization code grant (OAuth 2.0 RFC 6749 §4.1) is the default path for Inbound Apps when a user must sign in and consent before a third-party application or AI agent receives a token. The client never sees the user's password — it receives a one-time code and exchanges it at the token endpoint.

Use this grant for partner integrations, OAuth marketplaces, MCP clients with user consent, and any scenario where someone explicitly approves scopes on your Resources.

How it works

1. The application redirects the user's browser to Descope's /authorize endpoint with response_type=code, the app's client_id, redirect_uri, requested scope, and optionally a resource (RFC 8707) targeting a specific API or MCP server.
2. The user authenticates through a Descope Flow and runs the inbound app's consent flow. Only scopes permitted by Policies appear.
3. Descope redirects back to the app's redirect_uri with a single-use authorization code.
4. The application sends a server-side POST to /token with grant_type=authorization_code, the code, client_id, and client authentication (client secret or PKCE code_verifier).
5. Descope validates the code and client, then returns an access token (and usually a refresh token and ID token). The access token carries scopes for the requested Resource; the app sends it when calling your API or MCP server.

PKCE

Public clients (SPAs, mobile apps, native agents without a stored secret) must use PKCE. Send code_challenge and code_challenge_method on /authorize, then code_verifier on /token.

Confidential clients (backend apps) may use a client secret instead. You can still require PKCE for confidential clients under Client Authentication.

Configure in the Console

Under the inbound app's Grant Types:

• Enable Authorization Code.
• Click Manage to set approved redirect URLs.
• Select a User Consent Flow.

Implement

See Using Inbound Apps → Authorization Code Flow for /authorize and /token examples, scope handling, and tenant consent.

After tokens are issued, renew them with the refresh token grant without sending the user through consent again (until consent expires).

Related

• Grant Types overview
• Authorization server → Authorize endpoint
• Session validation — enforce aud and scope on your API