openapi: 3.0.3
info:
title: Clerk Backend Account Portal Sign Ins API
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: support@clerk.com
name: Clerk Platform Team
url: https://clerk.com/support
description: 'The Clerk REST Backend API, meant to be accessed by backend servers.
### 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. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions).
Please see https://clerk.com/docs for more information.'
version: '2025-11-10'
termsOfService: https://clerk.com/terms
license:
name: MIT
url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: Sign Ins
description: Used to sign in a user in the current client.
paths:
/v1/client/sign_ins:
post:
security:
- {}
summary: Create a New Sign in or Replace the Current One.
description: 'Creates or replaces the current Sign in object.
In order to authenticate a Sign in in as few requests as possible,
you can pass in parameters to this request that can identify and verify the Sign in.
Parameter rules:
If the strategy equals `phone_code`, `email_code`, `web3_[provider]_signature`, `reset_password_code` or `reset_password_phone_code` then an identifier is required.
If the strategy equals `email_link` then an identifier is required and optionally redirect_url can be supplied.
If the strategy equals `password` then both an identifier and a password is required.
If the strategy equals `oauth_[provider]` or `saml` then a redirect_url is required, and an action_complete_redirect_url is optional.
If the strategy equals `oauth_token_[provider]` then at least one of code (grant code) or token (openID token) is required. Passing only the token will probably retrieve minimal information about the user from the OAuth provider. You can pass both code and token for the best results.
If the strategy equals `ticket` then ticket is required.
If the strategy equals `passkey` then no identifier is provided.
If the strategy equals `google_one_tap` then token is required.'
tags:
- Sign Ins
operationId: createSignIn
parameters:
- in: header
name: Origin
description: The origin of the request
schema:
type: string
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
strategy:
type: string
description: 'Strategy used to sign in.
Can be one of `phone_code`, `email_code`, `ticket`, `web3_[provider]_signature` `reset_password_code`, `reset_password_phone_code`, `email_link`, `oauth_[provider]`, `oauth_token_[provider]`, `saml`, `password`, `passkey`, `google_one_tap`'
nullable: true
identifier:
type: string
description: The unique identifier of the user. This changes depending on the strategy.
nullable: true
password:
type: string
description: The password of the user. Only used with password strategy.
nullable: true
ticket:
type: string
description: Ticket to be used for signing in.
nullable: true
redirect_url:
type: string
nullable: true
action_complete_redirect_url:
type: string
nullable: true
transfer:
type: boolean
nullable: true
code:
type: string
description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies.
nullable: true
token:
type: string
description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
nullable: true
oidc_login_hint:
type: string
description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
nullable: true
oidc_prompt:
type: string
description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials, this value might be adjusted for security reasons.
nullable: true
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'307':
description: Redirect, no body.
'400':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
'409':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}:
get:
summary: Retrieve Sign-in
description: 'Returns the sign-in with the given ID.
The sign in is returned only if it belongs to the requesting client and is not abandoned.'
tags:
- Sign Ins
operationId: getSignIn
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in to be retrieved.
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}/reset_password:
post:
summary: Reset Password on Sign-in
description: Reset password on sign-in.
tags:
- Sign Ins
operationId: resetPassword
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in to be retrieved.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
additionalProperties: false
properties:
password:
type: string
sign_out_of_other_sessions:
type: boolean
nullable: true
required:
- password
responses:
'200':
$ref: '#/components/responses/responses-Client.SignIn'
'400':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}/prepare_first_factor:
post:
summary: Prepare First Factor Verification
description: 'Prepares the verification object for the identified Sign in.
This step authenticates that the user is who they say they are.
Depending on the strategy, this request will do something different.
Parameter actions:
If the strategy equals email_code then this request will send an email with an OTP code.
If the strategy equals phone_code then this request will send an SMS with an OTP code.
If the strategy equals oauth_[provider] then this request generate a URL that the User needs to visit in order to authenticate.
If the strategy equals passkey then this request will begin the passkey registration flow.
Parameter rules:
If the strategy equals `oauth_[provider]` then a redirect_url is required, and an action_complete_redirect_url is optional.'
tags:
- Sign Ins
operationId: prepareSignInFactorOne
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in to be retrieved.
- in: header
name: Origin
description: The origin of the request
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
strategy:
type: string
description: 'The strategy to be prepared for first factor authentication.
Can be one of the following `email_code`, `email_link`,
`phone_code`, `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature`,
`web3_okx_wallet_signature`, `reset_password_phone_code`, `reset_password_email_code`,
`oauth_[provider]`, `saml`, `passkey`, `enterprise_sso`'
email_address_id:
type: string
description: Used with the `email_code`, `reset_password_email_code` and `email_link` strategies.
nullable: true
phone_number_id:
type: string
description: Used with the `phone_code` and `reset_password_phone_code` strategies.
nullable: true
web3_wallet_id:
type: string
description: Used with the `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature` and `web3_okx_wallet_signature` strategies.
nullable: true
passkey_id:
type: string
description: Used with the `passkey` strategy.
nullable: true
redirect_url:
type: string
description: Used with `email_link`, `oauth_[provider]`, and `saml` strategies.
nullable: true
action_complete_redirect_url:
type: string
description: Used with `oauth_[provider]` and `saml` strategies.
nullable: true
oidc_login_hint:
type: string
description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL.
nullable: true
oidc_prompt:
type: string
description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons.
nullable: true
required:
- strategy
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'400':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
'429':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}/attempt_first_factor:
post:
summary: Attempt First Factor Verification
description: 'Attempt the first verification.
Requires the sign in attempt to be identified, and the first factor verification to be prepared, unless you''re using a password.
Parameter rules:
If the strategy equals `email_code` or `phone_code` then a code is required.
If the strategy equals `password` then a password is required.'
tags:
- Sign Ins
operationId: attemptSignInFactorOne
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in.
- in: header
name: Origin
description: The origin of the request
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
strategy:
type: string
description: 'The strategy to be used for first factor authentication.
Can be one of the following `email_code`, `email_link`, `password`, `phone_code`,
`web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature`, `web3_okx_wallet_signature`,
`reset_password_phone_code`, `reset_password_email_code`, `passkey`, `google_one_tap`'
code:
type: string
description: The code that was sent to the email. Used with the `email_code`, `phone_code`, and `email_link` strategies.
nullable: true
password:
type: string
description: Used with the `password` and `reset_password_phone_code` strategies.
nullable: true
signature:
type: string
description: Used with the `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature` and `web3_okx_wallet_signature` strategies.
nullable: true
token:
type: string
description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies.
nullable: true
ticket:
type: string
deprecated: true
nullable: true
public_key_credential:
type: string
description: Used with the `passkey` strategy.
nullable: true
required:
- strategy
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'307':
description: Redirect, no body.
'400':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
'429':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}/prepare_second_factor:
post:
summary: Prepare Second Factor Verification
description: 'Prepare the second verification.
Requires the sign in attempt `status` to be equal to `needs_second_factor` or `needs_client_trust`.'
tags:
- Sign Ins
operationId: prepareSignInFactorTwo
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
strategy:
type: string
description: The strategy to be prepared for second factor authentication.
nullable: true
enum:
- phone_code
- email_code
- email_link
phone_number_id:
type: string
description: Used with the `phone_code` strategy.
nullable: true
email_address_id:
type: string
description: Used with the `email_code` and `email_link` strategies.
nullable: true
redirect_url:
type: string
description: Used with the `email_link` strategy. The redirect URL after email link verification.
nullable: true
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'400':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
/v1/client/sign_ins/{sign_in_id}/attempt_second_factor:
post:
summary: Attempt Second Factor Verification
description: 'Attempt the second verification.
Requires the sign in attempt `status` to be equal to `needs_second_factor` or `needs_client_trust`, and for the preparation step to have been called.'
tags:
- Sign Ins
operationId: attemptSignInFactorTwo
parameters:
- in: path
name: sign_in_id
required: true
schema:
type: string
description: The ID of the sign in.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
strategy:
type: string
description: The strategy to be attempted for second factor authentication.
enum:
- email_code
- phone_code
- totp
- backup_code
code:
type: string
description: Used with the `phone_code`, `totp` and `backup_code` strategies.
responses:
'200':
$ref: '#/components/responses/Client.SignIn'
'307':
description: Redirect, no body.
'400':
$ref: '#/components/responses/ClerkErrors'
'403':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/ClerkErrors'
/v1/tickets/accept:
get:
summary: Accept Ticket
description: 'Parses a ticket JWT and performs the necessary actions depending on the ticket''s source type.
Depending on the ticket source type, a successful response can either redirect to a new location
with the ticket in the query string, or respond directly with a text/html content type for the response body.'
operationId: acceptTicket
tags:
- Sign Ins
parameters:
- in: query
name: ticket
required: true
schema:
type: string
description: The JWT with verification information
responses:
'200':
description: Successful response with a plain text or HTML body.
'302':
description: Redirect
'303':
description: Redirect
'400':
$ref: '#/components/responses/ClerkErrors'
'404':
$ref: '#/components/responses/ClerkErrors'
/v1/verify:
get:
summary: Attempt Email Link Verification
description: Attempt to verify a verification with email_link strategy.
operationId: verify
tags:
- Sign Ins
parameters:
- in: query
name: token
required: true
schema:
type: string
description: The JWT with verification information
responses:
'200':
description: OK
'303':
description: Redirect
'400':
$ref: '#/components/responses/ClerkErrors'
components:
schemas:
Stubs.Verification.GoogleOneTap:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- verification_google_one_tap
status:
type: string
enum:
- unverified
- verified
strategy:
type: string
enum:
- google_one_tap
expire_at:
type: integer
nullable: true
attempts:
type: integer
nullable: true
required:
- status
- strategy
Token:
type: object
additionalProperties: false
properties:
object:
type: string
description: 'String representing the object''s type. Objects of the same type share the same value.
'
enum:
- token
jwt:
type: string
description: 'String representing the encoded JWT value.
'
required:
- object
- jwt
Stubs.Verification.SAML:
type: object
properties:
object:
type: string
enum:
- verification_saml
status:
type: string
enum:
- unverified
- verified
- failed
- expired
- transferable
strategy:
type: string
enum:
- saml
external_verification_redirect_url:
nullable: true
type: string
error:
allOf:
- $ref: '#/components/schemas/ClerkError'
- type: object
nullable: true
expire_at:
type: integer
nullable: true
attempts:
type: integer
nullable: true
required:
- status
- strategy
Client.PublicUserData:
type: object
additionalProperties: false
properties:
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
image_url:
type: string
nullable: true
has_image:
type: boolean
identifier:
type: string
profile_image_url:
type: string
nullable: true
deprecated: true
description: Use `image_url` instead.
user_id:
type: string
nullable: true
username:
type: string
nullable: true
banned:
type: boolean
required:
- first_name
- last_name
- identifier
- has_image
Client.SessionBase:
type: object
properties:
id:
type: string
object:
type: string
description: 'String representing the object''s type. Objects of the same type share the same value.
'
enum:
- session
status:
type: string
enum:
- active
- revoked
- ended
- expired
- removed
- abandoned
expire_at:
type: integer
format: int64
abandon_at:
type: integer
format: int64
last_active_at:
type: integer
format: int64
last_active_token:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/Token'
actor:
type: object
nullable: true
additionalProperties: true
required:
- id
- object
- status
- expire_at
- abandon_at
- last_active_at
Client.Client:
type: object
nullable: true
properties:
object:
type: string
description: String representing the object's type. Objects of the same type share the same value.
enum:
- client
id:
type: string
description: String representing the identifier of the session.
sessions:
type: array
items:
$ref: '#/components/schemas/Client.Session'
sign_in:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/Client.SignIn'
sign_up:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/Client.SignUp'
last_active_session_id:
nullable: true
type: string
description: Last active session_id.
last_authentication_strategy:
nullable: true
type: string
description: 'The authentication strategy that was last used to authenticate the user on this client.
'
cookie_expires_at:
nullable: true
type: integer
format: int64
description: Unix timestamp of the cookie expiration.
captcha_bypass:
type: boolean
description: Whether the client can bypass CAPTCHA.
created_at:
type: integer
format: int64
description: Unix timestamp of creation.
updated_at:
type: integer
format: int64
description: Unix timestamp of last update.
required:
- object
- id
- sessions
- sign_in
- sign_up
- last_active_session_id
- last_authentication_strategy
- cookie_expires_at
- captcha_bypass
- created_at
- updated_at
schemas-Client.ClientWrappedSignIn:
type: object
additionalProperties: false
properties:
response:
$ref: '#/components/schemas/Client.SignIn'
client:
$ref: '#/components/schemas/Client.Client'
required:
- response
- client
Client.ClientWrappedSignIn:
type: object
additionalProperties: false
properties:
response:
$ref: '#/components/schemas/schemas-Client.SignIn'
client:
$ref: '#/components/schemas/schemas-Client.Client'
required:
- response
- client
Stubs.Verification.Password:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- verification_password
status:
type: string
enum:
- unverified
- verified
strategy:
type: string
enum:
- password
attempts:
type: integer
nullable: true
expire_at:
type: integer
nullable: true
required:
- status
- strategy
Client.EmailAddress:
type: object
additionalProperties: false
properties:
id:
type: string
object:
type: string
description: 'String representing the object''s type. Objects of the same type share the same value.
'
enum:
- email_address
email_address:
type: string
reserved:
type: boolean
verification:
type: object
nullable: true
oneOf:
- $ref: '#/components/schemas/Stubs.Verification.OTP'
- $ref: '#/components/schemas/Stubs.Verification.Invitation'
- $ref: '#/components/schemas/Stubs.Verification.Link'
- $ref: '#/components/schemas/Stubs.Verification.Ticket'
- $ref: '#/components/schemas/Stubs.Verification.Admin'
- $ref: '#/components/schemas/Stubs.Verification.FromOauth'
- $ref: '#/components/schemas/Stubs.Verification.SAML'
linked_to:
type: array
items:
$ref: '#/components/schemas/Stubs.Identification.Link'
matches_sso_connection:
description: 'Indicates whether this email address domain matches an active enterprise connection.
'
type: boolean
created_at:
type: integer
format: int64
description: 'Unix timestamp of creation
'
updated_at:
type: integer
format: int64
description: 'Unix timestamp of creation
'
required:
- id
- object
- email_address
- verification
- linked_to
- reserved
- created_at
- updated_at
Client.PhoneNumber:
type: object
additionalProperties: false
properties:
id:
type: string
object:
type: string
description: 'String representing the object''s type. Objects of the same type share the same value.
'
enum:
- phone_number
phone_number:
type: string
reserved_for_second_factor:
type: boolean
default_second_factor:
type: boolean
reserved:
type: boolean
verification:
nullable: true
type: object
oneOf:
- $ref: '#/components/schemas/Stubs.Verification.OTP'
- $ref: '#/components/schemas/Stubs.Verification.Admin'
linked_to:
type: array
items:
$ref: '#/components/schemas/Stubs.Identification.Link'
backup_codes:
type: array
items:
type: string
nullable: true
created_at:
type: integer
format: int64
description: 'Unix timestamp of creation
'
updated_at:
type: integer
format: int64
description: 'Unix timestamp of creation
'
required:
- id
- object
- phone_number
- verification
- linked_to
- reserved
- created_at
- updated_at
ClerkError:
type: object
properties:
message:
type: string
long_message:
type: string
code:
type: string
meta:
type: object
required:
- message
- long_message
- code
Stubs.SignUpVerification.AdditionalFields:
type: object
properties:
next_action:
type: string
enum:
- needs_prepare
- needs_attempt
- ''
supported_strategies:
type: array
items:
type: string
required:
- next_action
- supported_strategies
Client.SignIn:
type: object
additionalProperties: false
properties:
object:
type: string
description: String representing the object's type. Objects of the same type share the same value.
enum:
- sign_in_attempt
id:
type: string
status:
type: string
enum:
- abandoned
- needs_identifier
- needs_first_factor
- needs_second_factor
- needs_client_trust
- needs_new_password
- needs_protect_check
- complete
supported_identifiers:
type: array
description: List of supported identifiers that can be used to sign in.
items:
type: string
enum:
- email_address
- phone_number
- username
- web3_wallet
- passkey
supported_first_factors:
type: array
nullable: true
items:
$ref: '#/components/schemas/Stubs.SignInFactor'
supported_second_factors:
type: array
nullable: true
items:
$ref: '#/components/schemas/Stubs.SignInFactor'
first_factor_verification:
type: object
nullable: true
oneOf:
- $ref: '#/components/schemas/Stubs.Verification.Password'
- $ref: '#/components/schemas/Stubs.Verification.Oauth'
- $ref: '#/components/schemas/Stubs.Verification.OTP'
- $ref: '#/components/schemas/Stubs.Verification.Link'
- $ref: '#/components/schemas/Stubs.Verification.Web3Signature'
- $ref: '#/components/schemas/Stubs.Verification.Ticket'
- $ref: '#/components/schemas/Stubs.Verification.SAML'
- $ref: '#/components/schemas/Stubs.Verification.Passkey'
- $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap'
second_factor_verification:
type: object
nullable: true
oneOf:
- $ref: '#/components/schemas/Stubs.Verification.OTP'
- $ref: '#/components/schemas/Stubs.Verification.TOTP'
- $ref: '#/components/schemas/Stubs.Verification.Ticket'
- $ref: '#/components/schemas/Stubs.Verification.BackupCode'
identifier:
nullable: tru
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-sign-ins-api-openapi.yml