Start an authorization session

Start an OAuth authorization session for the caller. If the user is already authorized, the response can be completed immediately. Otherwise, the response includes a verification URL that the user must visit to complete authorization.

POST /auth-sessions

Start an authorization session

cURL

curl --request POST \
  --url https://api.smith.langchain.com/v1/deepagents/auth-sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "provider_id": "github-tools-provider",
  "scopes": [
    "repo"
  ],
  "strategy": "REUSE"
}
'

200

Example

{ "id": "<string>", "provider_id": "<string>", "verification_url": "<string>", "token": "<string>", "metadata": {} }

Authorizations

X-Api-Key · string · header · default: LANGSMITH_API_KEY · required

Body

application/json

provider_id · string · required

OAuth provider ID returned by the MCP OAuth provider registration endpoint.

scopes · string[] · required

OAuth scopes to request.

strategy · enum<string> · required

REUSE returns an existing valid token when possible. CREATE starts a fresh authorization session.

Available options: REUSE, CREATE

agent_id · string

Optional agent ID to associate with the session.

token_id · string

Optional token ID to reuse or update.

is_default · boolean

Whether the resulting token should be the default token for this provider.

Response

200

application/json

Existing token reused; no new session created.

id · string

Authorization session ID. Present for pending sessions.

provider_id · string

status · enum<string>

Current authorization session status.

Available options: PENDING, COMPLETED, CONNECTION_REQUIRED, TOKEN_EXPIRED

verification_url · string<uri>

URL the user must visit to complete authorization. Present when status is PENDING.

token · string

Token identifier or token payload returned when authorization is already complete. Treat this value as sensitive.

metadata · object