Clerk docs

OAuth2 Identify Provider

Requests for the OAuth2 authorization flow.

Request OAuth2 authorization

Request OAuth2 authorization. If successful, receive authorization grant via redirect.

Responses
200

Success for 'form_post' response mode

302

Redirect, no body.

303

Redirect, no body.

400

Bad request error, for example a request parameter is invalid.

401

Unauthorized error, for example the provided client is invalid.

403

Forbidden error, for example you are trying to use a satellite domain

get/oauth/authorize

Request OAuth2 authorization

Request OAuth2 authorization. If successful, receive authorization grant via redirect.

Responses
200

Success for 'form_post' response mode

302

Redirect, no body.

303

Redirect, no body.

400

Bad request error, for example a request parameter is invalid.

401

Unauthorized error, for example the provided client is invalid.

403

Forbidden error, for example you are trying to use a satellite domain

post/oauth/authorize

Get OAuth2 token

Get OAuth2 token in exchange for a valid authorization grant.

Responses
200

Fetch token for OAuth2 flow

400

Bad request error, for example a request parameter is invalid.

401

Unauthorized error, for example the provided client is invalid.

403

Forbidden error, for example you are trying to use a satellite domain

post/oauth/token
Response samples
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "scope": "string",
  • "id_token": "string"
}

Get user info after OAuth2 flow

Get user info in exchange for a valid OAuth2 access token.

Responses
200

Get user info after successful OAuth2 flow

400

Request was not successful

401

Request was not successful

403

Request was not successful

get/oauth/userinfo
Response samples
application/json
{
  • "object": "string",
  • "instance_id": "string",
  • "user_id": "string",
  • "sub": "string",
  • "email": "string",
  • "email_verified": true,
  • "family_name": "string",
  • "given_name": "string",
  • "name": "string",
  • "username": "string",
  • "preferred_username": "string",
  • "picture": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { }
}

Get user info after OAuth2 flow

Get user info in exchange for a valid OAuth2 access token.

Responses
200

Get user info after successful OAuth2 flow

400

Request was not successful

401

Request was not successful

403

Request was not successful

post/oauth/userinfo
Response samples
application/json
{
  • "object": "string",
  • "instance_id": "string",
  • "user_id": "string",
  • "sub": "string",
  • "email": "string",
  • "email_verified": true,
  • "family_name": "string",
  • "given_name": "string",
  • "name": "string",
  • "username": "string",
  • "preferred_username": "string",
  • "picture": "string",
  • "public_metadata": { },
  • "private_metadata": { },
  • "unsafe_metadata": { }
}

Get information for an access or refresh token

Get information for an access or refresh token

Request
Request Body schema: application/x-www-form-urlencoded
token
required
string

The value of the access or the refresh token

token_type_hint
string or null

A hint about the type of the token submitted for introspection. Can be one of the following access_token and refresh_token

scope
string or null

The granted scopes for the token to check against

Responses
200

Get information for an access or refresh token

401

Unauthorized error, for example the provided client is invalid.

422

You are currently using the legacy OAuth 2.0 provider, please migrate to the new one via Clerk Dashboard.

post/oauth/token_info
Request samples
application/x-www-form-urlencoded
token=string&token_type_hint=string&scope=string
Response samples
application/json
{
  • "active": true,
  • "client_id": "string",
  • "iat": 0,
  • "scope": "string",
  • "sub": "string"
}

Get consent information

Get required consent information for a given OAuth Application Client ID and State

SecurityNone or DevBrowser
Request
path Parameters
client_id
required
string

The OAuth Application Client ID to get consent information for.

query Parameters
_clerk_session_id
string

The session_id associated with the requesting user.

Responses
200

OAuth2 consent information for a given OAuth Application Client ID and State

400

Request was not successful

401

Request was not successful

403

Request was not successful

404

Request was not successful

422

Request was not successful

get/v1/me/oauth/consent/{client_id}
Response samples
application/json
{
  • "oauth_application_name": "string",
  • "client_id": "string",
  • "consented_scopes": [
    ]
}

Update OAuth2 consent

Update OAuth2 consent for a given session ID and state ID to help complete the /oauth/authorize flow.

SecurityNone or DevBrowser
Request
path Parameters
client_id
required
string

The OAuth Application Client ID to update consent for.

query Parameters
_clerk_session_id
string

The session_id associated with the requesting user.

Request Body schema: application/x-www-form-urlencoded
required
scope
string

Space delimited list of scopes to consent to. If not provided, the user will be considered consented to no scopes.

Responses
200

OAuth2 consent information for a given OAuth Application Client ID and State

400

Request was not successful

401

Request was not successful

403

Request was not successful

404

Request was not successful

422

Request was not successful

post/v1/me/oauth/consent/{client_id}
Request samples
application/x-www-form-urlencoded
scope=string
Response samples
application/json
{
  • "oauth_application_name": "string",
  • "client_id": "string",
  • "consented_scopes": [
    ]
}
➔ Next to OAuth2 Callbacks