openapi: 3.0.3
info:
title: Clerk Frontend API
version: v1
description: 'The Clerk REST Frontend API, meant to be accessed from a browser or native environment.
This is a Form Based API and all the data must be sent and formatted according to the `application/x-www-form-urlencoded` content type.
### Versions
When the API changes in a way that isn''t compatible with older versions, a new version is released.
Each version is identified by its release date, e.g. `2021-02-05`. For more information, please see [Clerk API Versions](https://clerk.com/docs/backend-requests/versioning/overview).
### Using the Try It Console
The `Try It` feature of the docs only works for **Development Instances** when using the `DevBrowser` security scheme.
To use it, first generate a dev instance token from the `/v1/dev_browser` endpoint.
Please see https://clerk.com/docs for more information.'
x-logo:
url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
altText: Clerk docs
href: https://clerk.com/docs
contact:
email: [email protected]
name: Clerk Team
url: https://clerk.com/support
termsOfService: https://clerk.com/terms
license:
name: MIT
url: https://github.com/clerk/javascript/blob/main/LICENSE
servers:
- url: https://{domain}.clerk.accounts.dev
variables:
domain:
default: example-destined-camel-13
description: Your Development Instance Frontend API Domain.
security:
- {}
- DevBrowser: []
- ProductionBrowser: []
- ProductionNativeApp: []
ProductionNativeFlag: []
tags:
- name: DevBrowser
description: Used to handle dev browsers.
- name: DevTools
description: Used to configure development instance settings.
- name: Well Known
description: Well-known endpoints like JWKS, deep linking, and openid-configuration.
- name: Health
description: Used to get the health status of the API.
- name: OAuth2 Identity Provider
description: Requests for the OAuth2 authorization flow.
- name: OAuth2 Callbacks
description: Used to receive callbacks from successful OAuth attempts.
- name: SAML
description: Used in authentication flows using SAML.
- name: Client
description: Used to interact with the Client Object.
- name: Sessions
description: Used to interact with the sessions of a client.
- name: Sign Ins
description: Used to sign in a user in the current client.
- name: Sign Ups
description: Used to sign up a new user in the current client.
- name: User
description: Used to interact with the properties of the current user.
- name: Active Sessions
description: Used to interact with the sessions of the current user.
- name: Email Addresses
description: Used to interact with the email addresses of the logged in user.
- name: Phone Numbers
description: Used to interact with the phone numbers of the logged in user.
- name: Web3 Wallets
description: Used to interact with the web3 wallets of the logged in user.
- name: Passkeys
description: Used to interact with the passkeys of the logged in user.
- name: External Accounts
description: Used to interact with the external accounts of the current user.
- name: TOTP
description: Used to interact with One Time Password authenticators of the current user.
- name: Backup Codes
description: Used to interact with the two factor authentication backup codes of the current user.
- name: Organizations Memberships
description: Used to interact with the current user's organization memberships, invitations and suggestions.
- name: Organization
description: Used to interact with an organization and its properties. The current user must be an administrator to access them.
- name: Organization Creation Defaults
description: Used to get suggested defaults when creating a new organization.
- name: Invitations
description: Used to interact with the invitations of an organization. The current user must be an administrator to access them.
- name: Members
description: Used to interact with the members of an organization. The current user must be an administrator to access them.
- name: Membership Requests
description: Used to interact with the members of an organization. The current user must be an administrator to access them.
- name: Domains
description: Used to interact with the members of an organization. The current user must be an administrator to access them.
- name: Environment
description: Used to get and update the current Environment
- name: Waitlist
description: Used to interact with the waitlist.
- name: API Keys
description: Endpoints for managing API Keys
- name: Enterprise Connections
description: Endpoints for managing enterprise connections.
- name: Plans
description: Used to interact with plans that users and organizations can purchase.
- name: Subscriptions
description: Used to interact with subscriptions belonging to users and organizations.
- name: Subscription Items
description: Used to interact with subscription items belonging to users and organizations.
- name: Checkouts
description: Used to interact with the checkout flow.
- name: Payment Methods
description: Used to interact with payment methods belonging to users and organizations.
- name: Statements
description: Used to interact with billing statements for users and organizations.
- name: Payment Attempts
description: Used to interact with payment attempts for users and organizations.
paths:
/.well-known/assetlinks.json:
get:
summary: Get Android Asset Links
description: Get Android asset links for universal/deep linking
operationId: getAndroidAssetLinks
security: []
tags:
- Well Known
responses:
'200':
$ref: '#/components/responses/WellKnown.Assetlinks'
/.well-known/jwks.json:
get:
summary: JWKS
description: Retrieve the JSON Web Key Set of the instance
operationId: getJWKS
security: []
tags:
- Well Known
responses:
'200':
$ref: '#/components/responses/WellKnown.JWKS'
'500':
$ref: '#/components/responses/ClerkErrors'
/.well-known/apple-app-site-association:
get:
summary: Apple App Site Association
description: Retrieve the Apple App Site Association file of the instance
operationId: getAppleAppSiteAssociation
security: []
tags:
- Well Known
responses:
'200':
$ref: '#/components/responses/WellKnown.AppleAppSiteAssociation'
'500':
$ref: '#/components/responses/ClerkErrors'
/.well-known/openid-configuration:
get:
summary: Basic OpenID Configuration Payload
description: Get a basic OpenID configuration payload
operationId: getOpenIDConfiguration
security: []
tags:
- Well Known
responses:
'200':
$ref: '#/components/responses/WellKnown.OpenIDConfiguration'
/.well-known/oauth-authorization-server:
get:
summary: OAuth 2.0 Authorization Server Metadata
description: Get the OAuth 2.0 Authorization Server Metadata according to RFC 8414
operationId: getOAuth2AuthorizationServerMetadata
security: []
tags:
- Well Known
responses:
'200':
$ref: '#/components/responses/WellKnown.OAuth2AuthorizationServerMetadata'
/oauth/authorize:
get:
summary: Request OAuth2 Authorization
description: Request OAuth2 authorization. If successful, receive authorization grant via redirect.
operationId: requestOAuthAuthorize
security: []
tags:
- OAuth2 Identity Provider
parameters:
- name: response_type
in: query
required: true
description: The authorization flow type. Must be `code` for authorization code flow.
schema:
type: string
enum:
- code
- name: client_id
in: query
required: true
description: The OAuth2 client ID of the OAuth application.
schema:
type: string
- name: redirect_uri
in: query
required: false
description: The URI to redirect to after authorization. Must be registered for the OAuth application.
schema:
type: string
format: uri
- name: scope
in: query
required: false
style: spaceDelimited
explode: false
description: Space-separated list of scopes being requested. Available scopes are `email`, `profile`, `openid`, `public_metadata`, and `private_metadata`. Defaults to `profile email` if not provided.
schema:
type: array
items:
type: string
enum:
- email
- profile
- openid
- offline_access
- public_metadata
- private_metadata
- name: state
in: query
required: false
description: An opaque value used to maintain state between the request and callback (minimum 8 characters). Required to prevent CSRF attacks unless PKCE parameters (`code_challenge` and `code_challenge_method`) are provided.
schema:
type: string
minLength: 8
- name: prompt
in: query
required: false
style: spaceDelimited
explode: false
description: Space-separated list of prompts. Supported values are `none` (no user interaction), `login` (force re-authentication), and `consent` (force consent screen).
schema:
type: array
items:
type: string
enum:
- none
- login
- consent
- name: code_challenge
in: query
required: false
description: The code challenge for PKCE (Proof Key for Code Exchange). Required for public clients.
schema:
type: string
- name: code_challenge_method
in: query
required: false
description: The method used to generate the code challenge. Must be `S256`.
schema:
type: string
enum:
- S256
- name: response_mode
in: query
required: false
description: The method used to return authorization response parameters. Supported values are `query` (parameters in URL query string) and `form_post` (parameters in POST body).
schema:
type: string
enum:
- query
- form_post
- name: nonce
in: query
required: false
description: String value used to associate a client session with an ID Token and to mitigate replay attacks. Used in OpenID Connect flows.
schema:
type: string
responses:
'200':
description: Success for 'form_post' response mode
'302':
description: Redirect, no body.
'303':
description: Redirect, no body.
'400':
description: Bad request error, for example a request parameter is invalid.
'401':
description: Unauthorized error, for example the provided client is invalid.
'403':
description: Forbidden error, for example you are trying to use a satellite domain
post:
summary: Request OAuth2 Authorization
description: Request OAuth2 authorization. If successful, receive authorization grant via redirect.
operationId: requestOAuthAuthorizePOST
security: []
tags:
- OAuth2 Identity Provider
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
response_type:
type: string
description: The authorization flow type. Must be `code` for authorization code flow.
enum:
- code
client_id:
type: string
description: The OAuth2 client ID of the OAuth application.
redirect_uri:
type: string
format: uri
nullable: true
description: The URI to redirect to after authorization. Must be registered for the OAuth application.
scope:
type: string
nullable: true
description: Space-separated list of scopes being requested. Available scopes are `email`, `profile`, `openid`, `public_metadata`, and `private_metadata`. Defaults to `profile email` if not provided. Multiple values should be space-delimited (e.g., "email profile openid").
state:
type: string
nullable: true
description: An opaque value used to maintain state between the request and callback (minimum 8 characters). Required to prevent CSRF attacks unless PKCE parameters (`code_challenge` and `code_challenge_method`) are provided.
minLength: 8
prompt:
type: string
nullable: true
description: Space-separated list of prompts. Supported values are `none` (no user interaction), `login` (force re-authentication), and `consent` (force consent screen). Multiple values should be space-delimited (e.g., "login consent").
code_challenge:
type: string
nullable: true
description: The code challenge for PKCE (Proof Key for Code Exchange). Required for public clients.
code_challenge_method:
type: string
nullable: true
description: The method used to generate the code challenge. Must be `S256`.
enum:
- S256
response_mode:
type: string
nullable: true
description: The method used to return authorization response parameters. Supported values are `query` (parameters in URL query string) and `form_post` (parameters in POST body).
enum:
- query
- form_post
nonce:
type: string
nullable: true
description: String value used to associate a client session with an ID Token and to mitigate replay attacks. Used in OpenID Connect flows.
required:
- response_type
- client_id
responses:
'200':
description: Success for 'form_post' response mode
'302':
description: Redirect, no body.
'303':
description: Redirect, no body.
'400':
description: Bad request error, for example a request parameter is invalid.
'401':
description: Unauthorized error, for example the provided client is invalid.
'403':
description: Forbidden error, for example you are trying to use a satellite domain
/oauth/internal-consent: {}
/oauth/register:
post:
summary: Register OAuth 2.0 Client
description: "Registers a new OAuth 2.0 client with the authorization server according to RFC 7591\n(OAuth 2.0 Dynamic Client Registration Protocol).\n\nThis endpoint allows clients to dynamically register by submitting client metadata.\nUpon successful registration, the authorization server assigns a unique client identifier\nand optionally a client secret (for confidential clients).\n\n**Authentication:** This endpoint does not require authentication as it is used for\ninitial client registration. However, the endpoint is disabled by default and must\nbe enabled in the Instance settings.\n\n**Client Types:**\n- **Confidential clients** receive both a `client_id` and `client_secret`\n- **Public clients** (using `token_endpoint_auth_method: none`) receive only a `client_id`\n\n**Key Points:**\n- All dynamically registered clients must use the consent screen (cannot be disabled)\n- PKCE is not required for dynamically registered clients\n- The `redirect_uris` field is required and must\
\ contain at least one valid redirect URI\n- If `client_name` is not provided, the `client_id` will be used as the display name\n- If `scope` is not provided, default scopes will be assigned\n- The `token_endpoint_auth_method` values `client_secret_basic` and `client_secret_post` are\n treated equivalently in the current implementation; both methods can be used at the\n token endpoint\n\nSee [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) for complete specification details."
operationId: registerOAuthClient
security: []
tags:
- OAuth2 Identity Provider
requestBody:
description: 'Client metadata as defined in RFC 7591 Section 2. The client metadata includes
information about the client such as its name, redirect URIs, and authentication method.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth.DynamicClientRegistrationRequest'
examples:
confidentialClient:
summary: Confidential Client Registration
description: Register a confidential client that will authenticate with client_secret_basic
value:
client_name: My Confidential App
client_uri: https://example.com
logo_uri: https://example.com/logo.png
redirect_uris:
- https://example.com/oauth/callback
token_endpoint_auth_method: client_secret_basic
scope: openid email profile
publicClient:
summary: Public Client Registration
description: Register a public client (no client secret)
value:
client_name: My Mobile App
client_uri: https://example.com
redirect_uris:
- myapp://oauth/callback
token_endpoint_auth_method: none
scope: openid email profile
minimalClient:
summary: Minimal Client Registration
description: Register a client with only required fields
value:
redirect_uris:
- https://example.com/callback
responses:
'201':
$ref: '#/components/responses/OAuth.DynamicClientRegistration'
'400':
$ref: '#/components/responses/OAuth.DynamicClientRegistrationError'
'422':
description: 'Unprocessable entity error. The dynamic client registration feature may not be enabled
for this instance.'
'500':
description: 'Internal server error. The authorization server encountered an unexpected condition
that prevented it from fulfilling the registration request.'
/oauth/token:
post:
summary: Get OAuth2 Token
description: "Exchange an authorization grant for OAuth2 tokens (access token, refresh token, and optionally ID token).\n\nThis endpoint implements the OAuth 2.0 Token Endpoint (RFC 6749) and OpenID Connect token endpoint.\nIt supports two grant types: `authorization_code` and `refresh_token`.\n\n#### Grant Types\n\n- **`authorization_code`**: Exchange an authorization code for tokens\n- **`refresh_token`**: Refresh an access token using a refresh token\n\n#### Authentication\n\n- **Confidential clients**: Must authenticate using one of the following methods:\n - HTTP Basic Authentication: `Authorization: Basic base64(client_id:client_secret)`\n - Client credentials in request body: Include `client_id` and `client_secret` in form fields\n - *Note: Both methods (`client_secret_basic` and `client_secret_post`) are treated equivalently*\n- **Public clients** (PKCE flow): No client secret required. Must provide `client_id` and `code_verifier` in request body.\n\n#### PKCE (Proof Key\
\ for Code Exchange)\n\nPublic clients and clients that cannot securely store a client secret must use PKCE (RFC 7636).\nWhen using PKCE:\n- Include `code_challenge` and `code_challenge_method` in the authorization request\n- Include `code_verifier` in the token request (instead of `client_secret`)\n\n#### Scopes\n\nAvailable scopes:\n- `openid` - Enables OpenID Connect features, returns an `id_token` in the response\n- `email` - User's email address\n- `profile` - Basic profile information (name, username, picture, etc.)\n- `public_metadata` - Clerk custom scope for public metadata\n- `private_metadata` - Clerk custom scope for private metadata\n\nDefault scopes (if not specified): `email profile`\n\n#### Token Lifespans\n\n- **Access token**: 1 day (86400 seconds)\n- **Refresh token**: 10 years\n- **ID token**: 1 day (86400 seconds)\n- **Authorization code**: 10 minutes (must be exchanged within this time)\n\n#### OpenID Connect\n\nWhen the `openid` scope is included in the authorization\
\ request, the token response will include\nan `id_token` field containing a signed JWT with user identity information per the OpenID Connect specification.\nThe `id_token` will be refreshed along with the access token when using the `refresh_token` grant type."
operationId: getOAuthToken
security:
- ClientCredentials: []
- {}
tags:
- OAuth2 Identity Provider
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
properties:
grant_type:
type: string
description: 'The grant type being used.
- `authorization_code`: Exchange an authorization code for tokens
- `refresh_token`: Refresh an access token'
enum:
- authorization_code
- refresh_token
code:
type: string
nullable: true
description: 'The authorization code received from the authorization endpoint.
**Required when `grant_type=authorization_code`**.'
redirect_uri:
type: string
nullable: true
description: 'The redirect URI used in the authorization request. Must match exactly.
**Required when `grant_type=authorization_code`**.'
code_verifier:
type: string
nullable: true
description: 'The PKCE code verifier that corresponds to the `code_challenge` sent in the authorization request.
**Required for public clients using PKCE with `grant_type=authorization_code`**.
Confidential clients using `client_secret` should not include this parameter.'
client_id:
type: string
nullable: true
description: 'The OAuth 2.0 client identifier.
**Required for public clients** (those not using HTTP Basic Authentication).
For confidential clients, can be provided here or via HTTP Basic Authentication.'
client_secret:
type: string
nullable: true
description: 'The OAuth 2.0 client secret.
**Required for confidential clients** (unless using HTTP Basic Authentication).
Public clients using PKCE should not include this parameter.'
refresh_token:
type: string
nullable: true
description: 'The refresh token issued to the client.
**Required when `grant_type=refresh_token`**.'
scope:
type: string
nullable: true
description: 'Space-separated list of scopes for the access token.
**Optional when `grant_type=refresh_token`**.
If provided, the requested scope must not exceed the scope originally granted.
If omitted, the same scope as originally granted will be used.'
examples:
authorizationCodeConfidential:
summary: Authorization Code - Confidential Client
description: Exchange an authorization code for tokens using a confidential client with client secret
value:
grant_type: authorization_code
code: clk_code_abc123xyz
redirect_uri: https://example.com/oauth/callback
client_id: client_abc123
client_secret: secret_xyz789
authorizationCodePKCE:
summary: Authorization Code - Public Client with PKCE
description: Exchange an authorization code for tokens using PKCE (public client, no client secret)
value:
grant_type: authorization_code
code: clk_code_abc123xyz
redirect_uri: https://example.com/oauth/callback
client_id: client_abc123
code_verifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
refreshToken:
summary: Refresh Token
description: Refresh an access token using a refresh token
value:
grant_type: refresh_token
refresh_token: clk_refresh_abc123xyz
client_id: client_abc123
client_secret: secret_xyz789
responses:
'200':
$ref: '#/components/responses/OAuth.Token'
'400':
$ref: '#/components/responses/OAuth.TokenError400'
'401':
$ref: '#/components/responses/OAuth.TokenError401'
'403':
description: Forbidden error, for example you are trying to use a satellite domain
/oauth/userinfo:
get:
summary: Get User Info After OAuth2 Flow
description: Get user info in exchange for a valid OAuth2 access token.
operationId: getOAuthUserInfo
security: []
tags:
- OAuth2 Identity Provider
responses:
'200':
$ref: '#/components/responses/OAuth.UserInfo'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
post:
summary: Get User Info After OAuth2 Flow
description: Get user info in exchange for a valid OAuth2 access token.
operationId: getOAuthUserInfoPOST
security: []
tags:
- OAuth2 Identity Provider
responses:
'200':
$ref: '#/components/responses/OAuth.UserInfo'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
/oauth/token_info:
post:
summary: Get Information for an Access or Refresh Token
description: Get information for an access or refresh token
operationId: getOAuthTokenInfo
security: []
tags:
- OAuth2 Identity Provider
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
token:
type: string
description: The value of the access or the refresh token
token_type_hint:
type: string
description: A hint about the type of the token submitted for introspection. Can be one of the following `access_token` and `refresh_token`
nullable: true
scope:
type: string
description: The granted scopes for the token to check against
nullable: true
required:
- token
responses:
'200':
$ref: '#/components/responses/OAuth.TokenInfo'
'401':
description: Unauthorized error, for example the provided client is invalid.
'422':
description: You are currently using the legacy OAuth 2.0 provider, please migrate to the new one via Clerk Dashboard.
/oauth/token/revoke:
post:
summary: Revoke OAuth2 Token
description: 'Revoke OAuth2 token by token.
#### Authentication
- **Confidential clients**: Must authenticate using HTTP Basic Authentication with Client ID as username and Client Secret as password in the Authorization header.'
operationId: revokeOAuthToken
security:
- ClientCredentials: []
tags:
- OAuth2 Identity Provider
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
additionalProperties: false
properties:
token:
type: string
description: The token to revoke.
nullable: false
token_type_hint:
type: string
description: A hint about the type of the token to be revoked.
nullable: true
enum:
- access_token
- refresh_token
responses:
'200':
description: Success, no content.
'400':
$ref: '#/components/responses/OAuth.TokenError400'
'401':
$ref: '#/components/responses/OAuth.TokenError401'
/v1/me/oauth/consent/{client_id}:
get:
summary: Get Consent Information
description: 'Returns the scopes for a given OAuth Application Client ID.
An optional `scope` query parameter can restrict the returned scopes to only those requested.
The OAuth application must have consent screen enabled.
'
operationId: getOAuthConsent
security:
- {}
- DevBrowser: []
tags:
- OAuth2 Identity Provider
parameters:
- in: path
name: client_id
required: true
schema:
type: string
description: The OAuth Application Client ID to get consent information for.
- in: query
name: scope
required: false
schema:
type: string
description: Optional space-separated list of scopes to restrict the response to only those requested.
responses:
'200':
$ref: '#/components/responses/OAuth.ConsentInfo'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
post:
summary: Submit OAuth2 Consent Decision
description: 'Submits the user''s consent decision for an OAuth2 authorization request.
This endpoint allows building custom consent portals as a replacement for
the default account-portal-rendered consent screen.
The OAuth application must have the consent screen enabled. On grant, the
flow continues just like the standard `/oauth/authorize` endpoint and
returns the appropriate redirect.
In addition to the fields documented below, the request body must
re-submit the standard OAuth2 authorize parameters from the original
`/oauth/authorize` request: `response_type`, `redirect_uri`, `scope`,
`state`, `nonce`, `code_challenge`, and `code_challenge_method`. These
are forwarded as-is to the authorize flow.
'
operationId: submitOAuthConsent
security:
- {}
- DevBrowser: []
tags:
- OAuth2 Identity Provider
parameters:
- in: path
name: client_id
required: true
schema:
type: string
description: The OAuth Application Client ID the consent decision applies to.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- consented
properties:
consented:
type: boolean
description: 'The user''s consent decision. `true
# --- truncated at 32 KB (439 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-frontend-api-openapi.yml