Authorization Server Endpoints

When you configure an Inbound App, Descope acts as the OAuth 2.0 / OpenID Connect authorization server for that client.

Third-party applications, AI agents, and MCP clients call a shared set of HTTP endpoints under /oauth2/v1/apps/ to start user login, exchange codes for tokens, refresh sessions, and read token claims.

Each Inbound App also exposes a Discovery URL and Issuer in the Descope Console (see Creating Inbound Apps). Standard OAuth libraries use those values to resolve the same endpoints listed below automatically.

Base URL

All authorization server routes are rooted at:

{baseUrl}/oauth2/v1/apps/...

Endpoint Reference

Discovery and JWKs

Inbound Apps are OpenID Connect-compatible. For each app, the Console provides:

• Discovery URL — OpenID Provider metadata (authorization_endpoint, token_endpoint, jwks_uri, supported scopes, and grant types).
• Issuer — Value used to validate iss on ID tokens and access tokens.

Project-level well-known documents are also available when you need metadata scoped to the whole project:

https://api.descope.com/v1/apps/{projectId}/.well-known/openid-configuration
https://api.descope.com/v1/apps/{projectId}/.well-known/oauth-authorization-server

MCP Server Resources

MCP servers are defined as MCP Server Resources—the same OAuth resource model as API Resources. Descope uses one authorization server for all Inbound Apps; to authenticate against a specific Resource (including an MCP server), include the resource parameter (RFC 8707) on the authorize or token request. Use the Resource identifier from the console—typically your MCP server URL, which also appears in the token aud claim.

MCP clients discover that Resource through OAuth Protected Resource Metadata on your server; see MCP discovery URL for the client-side discovery flow.

Token Endpoint

The token endpoint is the central exchange point for Inbound Apps. Send application/x-www-form-urlencoded (or JSON, per the API schema) with a grant_type and the parameters required for that grant.

Common optional parameters on the token endpoint include:

• scope — Requested OAuth scopes (must be allowed on the Inbound App and, for user flows, approved in consent).
• resource — RFC 8707 resource indicator (single Resource URI per request). Required when issuing tokens for a specific API or MCP Server Resource; pass the same value on authorize and token requests.
• audience — Target audience for issued tokens or exchanges.

Example (authorization code exchange):

curl -X POST "https://api.descope.com/oauth2/v1/apps/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "code=<AUTHORIZATION_CODE>" \
  -d "redirect_uri=https://yourapp.com/callback"

See the Token endpoint API reference for the full request and response schema.

Authorize Endpoint

The authorize endpoint starts interactive login and consent. Browser-based apps redirect users with query parameters such as client_id, redirect_uri, response_type=code, scope, state, PKCE fields (code_challenge, code_challenge_method), and optionally resource to target a specific Resource (required when authenticating to an MCP Server Resource).

Example redirect:

https://api.descope.com/oauth2/v1/apps/authorize?\
client_id=<CLIENT_ID>&\
redirect_uri=https://yourapp.com/callback&\
response_type=code&\
scope=openid%20email%20profile&\
state=<RANDOM_STATE>

When targeting an MCP Server Resource, add resource (URL-encoded Resource URI):

https://api.descope.com/oauth2/v1/apps/authorize?\
client_id=<CLIENT_ID>&\
redirect_uri=https://yourapp.com/callback&\
response_type=code&\
scope=mcp:tools.read&\
resource=https%3A%2F%2Fyour-mcp.example.com%2Fmcp&\
state=<RANDOM_STATE>

After the user completes the consent flow, Descope redirects back to redirect_uri with an authorization code. Exchange that code at the token endpoint, including the same resource value if you specified one at authorize time.

Revoke Endpoint

The revoke endpoint invalidates an access or refresh token (RFC 7009). Call it when a user disconnects an integration, you rotate credentials, or you need to end a session without waiting for natural expiry.

Send application/x-www-form-urlencoded (or JSON, per the API schema) with:

• token — The access or refresh token to revoke.
• token_type_hint — Optional hint: access_token or refresh_token.
• client_id / client_secret — Inbound App credentials (required for confidential clients).

Example (revoke a refresh token):

curl -X POST "https://api.descope.com/oauth2/v1/apps/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<REFRESH_TOKEN>" \
  -d "token_type_hint=refresh_token" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

Revoking a refresh token prevents future renewals at the token endpoint. Revoking an access token invalidates it for subsequent API calls.

See the Revoke token API reference for the full request and response schema.

User Info Endpoint

The UserInfo endpoint returns OpenID Connect claims for the subject of a valid access token. Use it when your app needs profile data (sub, email, name) or custom claims mapped in the Inbound App beyond what is embedded in the JWT.

Send the access token as a Bearer credential on the GET endpoint—the standard OIDC variant. A POST variant is available for clients that require it.

Example (GET):

curl "https://api.descope.com/oauth2/v1/apps/userinfo" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Example response (shape varies by scopes and Inbound App configuration):

{
  "sub": "U2lz...",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Jane Doe"
}

The access token must include the openid scope, and any scopes required for specific claims (such as email or profile). Claims returned depend on what the user approved during consent and how the Inbound App maps user attributes.

See the Get UserInfo and Post UserInfo API references for the full request and response schema.

Configure clients and scopes

• Create and manage Inbound Apps in the Console or via Management API.
• Map API permissions to OAuth scopes on Resources.
• Implement resource servers that validate Descope JWTs in Developing APIs with OAuth.

Related

• Using Inbound Apps — step-by-step flows for each grant type
• Inbound Apps API reference — interactive OpenAPI docs for every authorization server route
• Resources — define scopes and audiences your tokens target
• Agentic Identity Hub — agents, MCP servers, Connections, and STS token exchange