Clerk docs

Sign Ins

Used to sign in a user in the current client.

Create a new Sign In or replace the current one.

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.

SecurityNone
Request
Request Body schema: application/x-www-form-urlencoded
optional
strategy
string or null

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

identifier
string or null

The unique identifier of the user. This changes depending on the strategy.

password
string or null

The password of the user. Only used with password strategy.

ticket
string or null

Ticket to be used for signing in.

redirect_url
string or null
action_complete_redirect_url
string or null
transfer
boolean or null
code
string or null

The authorization or grant code for an OAuth exchange. Only used with oauth_token_[provider] strategies.

token
string or null

The ID token from an OpenID Connect flow. Only used with oauth_token_[provider] and google_one_tap strategies.

oidc_login_hint
string or null

Used with oauth_[provider]. The given value will be forwarded to the OIDC login_hint parameter of the generated redirect url.

oidc_prompt
string or null

Used with oauth_[provider]. 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.

Responses
200

Returns the sign in object, as well as the updated session object.

307

Redirect, no body.

400

Request was not successful

403

Request was not successful

404

Request was not successful

409

Request was not successful

422

Request was not successful

post/v1/client/sign_ins
Request samples
application/x-www-form-urlencoded
strategy=string&identifier=string&password=string&ticket=string&redirect_url=string&action_complete_redirect_url=string&transfer=true&code=string&token=string&oidc_login_hint=string&oidc_prompt=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Retrieve sign-in

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.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in to be retrieved.

Responses
200

Returns the sign in object, as well as the updated session object.

400

Request was not successful

401

Request was not successful

404

Request was not successful

get/v1/client/sign_ins/{sign_in_id}
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Reset password on sign-in

Reset password on sign-in.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in to be retrieved.

Request Body schema: application/x-www-form-urlencoded
password
string
sign_out_of_other_sessions
boolean or null
Responses
200

Returns the sign in object, as well as the updated session object.

400

Request was not successful

422

Request was not successful

post/v1/client/sign_ins/{sign_in_id}/reset_password
Request samples
application/x-www-form-urlencoded
password=string&sign_out_of_other_sessions=true
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Prepare First Factor Verification

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.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in to be retrieved.

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

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_coinbase_wallet_signature, web3_okx_wallet_signature, reset_password_phone_code, reset_password_email_code, oauth_[provider], saml, passkey

email_address_id
string or null

Used with the email_code, reset_password_email_code and email_link strategies.

phone_number_id
string or null

Used with the phone_code and reset_password_phone_code strategies.

web3_wallet_id
string or null

Used with the web3_metamask_signature, web3_coinbase_wallet_signature and web3_okx_wallet_signature strategies.

passkey_id
string or null

Used with the passkey strategy.

redirect_url
string or null

Used with email_link, oauth_[provider], and saml strategies.

action_complete_redirect_url
string or null

Used with oauth_[provider] and saml strategies.

oidc_login_hint
string or null

Used with oauth_[provider]. The given value will be forwarded to the OIDC login_hint parameter of the generated redirect url.

oidc_prompt
string or null

Used with oauth_[provider]. 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.

Responses
200

Returns the sign in object, as well as the updated session object.

400

Request was not successful

403

Request was not successful

404

Request was not successful

422

Request was not successful

429

Request was not successful

post/v1/client/sign_ins/{sign_in_id}/prepare_first_factor
Request samples
application/x-www-form-urlencoded
strategy=string&email_address_id=string&phone_number_id=string&web3_wallet_id=string&passkey_id=string&redirect_url=string&action_complete_redirect_url=string&oidc_login_hint=string&oidc_prompt=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Attempt First Factor Verification

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.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in.

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

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_coinbase_wallet_signature, web3_okx_wallet_signature, reset_password_phone_code, reset_password_email_code, passkey, google_one_tap

code
string or null

The code the was sent to the email. Used with the email_code, phone_code and email_link strategies.

password
string or null

Used with the password and reset_password_phone_code strategies.

signature
string or null

Used with the web3_metamask_signature, web3_coinbase_wallet_signature and web3_okx_wallet_signature strategies.

token
string or null

The ID token from an OpenID Connect flow. Only used with oauth_token_[provider] and google_one_tap strategies.

ticket
string or null
Deprecated
Responses
200

Returns the sign in object, as well as the updated session object.

307

Redirect, no body.

400

Request was not successful

403

Request was not successful

404

Request was not successful

422

Request was not successful

429

Request was not successful

post/v1/client/sign_ins/{sign_in_id}/attempt_first_factor
Request samples
application/x-www-form-urlencoded
strategy=string&code=string&password=string&signature=string&token=string&ticket=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Prepare Second Factor Verification

Prepare the second verification. Requires the sign in attempt status to be equal to needs_second_factor.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in.

Request Body schema: application/x-www-form-urlencoded
strategy
string or null

The strategy to be prepared for second factor authentication.

Value: "phone_code"
phone_number_id
string or null

Used with the phone_code strategy.

Responses
200

Returns the sign in object, as well as the updated session object.

400

Request was not successful

403

Request was not successful

422

Request was not successful

post/v1/client/sign_ins/{sign_in_id}/prepare_second_factor
Request samples
application/x-www-form-urlencoded
strategy=phone_code&phone_number_id=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Attempt Second Factor Verification

Attempt the second verification. Requires the sign in attempt status to be equal to needs_second_factor, and for the preparation step to have been called.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
path Parameters
sign_in_id
required
string

The id of the sign in.

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

The strategy to be attempted for first factor authentication.

Enum: "phone_code" "totp" "backup_code"
code
string

Used with the phone_code, totp and backup_code strategies.

Responses
200

Returns the sign in object, as well as the updated session object.

307

Redirect, no body.

400

Request was not successful

403

Request was not successful

422

Request was not successful

post/v1/client/sign_ins/{sign_in_id}/attempt_second_factor
Request samples
application/x-www-form-urlencoded
strategy=phone_code&code=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Accept ticket

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.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
query Parameters
ticket
required
string

The JWT with verification information

Responses
200

Successful response with a plain text or HTML body.

302

Redirect

303

Redirect

400

Request was not successful

404

Request was not successful

get/v1/tickets/accept
Response samples
application/json
{
  • "errors": [
    ],
  • "meta": { }
}

Attempt Email Link Verification

Attempt to verify a verification with email_link strategy.

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Request
query Parameters
token
required
string

The JWT with verification information

Responses
200

OK

303

Redirect

400

Request was not successful

get/v1/verify
Response samples
application/json
{
  • "errors": [
    ],
  • "meta": { }
}
➔ Next to Sign Ups