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 for an OpenID Connect flow. Only used with oauth_token_[provider] 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

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
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 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, 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 strategy.

passkey_id
string or null

Used with the passkey strategy.

redirect_url
string or null

Used with oauth_[provider] and saml strategy.

action_complete_redirect_url
string or null

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

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
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, 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 strategy.

redirect_url
string or null

Used with oauth_[provider] and saml strategies.

action_complete_redirect_url
string or null

Used with oauth_[provider] and saml 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&redirect_url=string&action_complete_redirect_url=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

Accept a ticket and redirects to the appropriate location along with the ticket

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

The JWT with verification information

Responses
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