Clerk docs

Sessions

Used to interact with the sessions of a client.

Remove client's sessions

Removes all the sessions of the current client without removing the __client cookie

SecurityNone or DevBrowser or ProductionBrowser or ProductionNativeApp and ProductionNativeFlag)
Responses
200

Returns the response for DELETE session object.

401

Request was not successful

404

Request was not successful

delete/v1/client/sessions
Response samples
application/json
{
  • "response": {
    },
  • "client": { }
}

Get Session

Returns the session with the given id

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

the user session id.

Responses
200

Returns a Session object.

401

Request was not successful

404

Request was not successful

get/v1/client/sessions/{session_id}
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Touch session

Specify the active session for the client.

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

the user session id.

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

The ID or slug of the organization to activate.

Responses
200

Returns a Session object.

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/client/sessions/{session_id}/touch
Request samples
application/x-www-form-urlencoded
active_organization_id=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

End Session

Marks the given session as ended.

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

the user session id.

Responses
200

Returns a Session object.

400

Request was not successful

404

Request was not successful

post/v1/client/sessions/{session_id}/end
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Remove Session

Delete the the given session.

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

the user session id.

Responses
200

Returns a Session object.

400

Request was not successful

404

Request was not successful

post/v1/client/sessions/{session_id}/remove
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Create Session Token

Create a session jwt for the authenticated requested user.

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

The user session id.

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

The organization id to associate with the token. The user must be a member of the organization. If present but empty, the personal workspace will be set as active. If absent, the previous active organization for the session will be used.

Responses
200

OK

401

Request was not successful

404

Request was not successful

post/v1/client/sessions/{session_id}/tokens
Request samples
application/x-www-form-urlencoded
organization_id=string
Response samples
application/json
{
  • "jwt": "string"
}

Create Session Token With JWT Template

Create a session jwt for the authenticated requested user.

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

the user session id.

template_name
required
string

the template name

Responses
200

OK

401

Request was not successful

post/v1/client/sessions/{session_id}/tokens/{template_name}
Response samples
application/json
{
  • "jwt": "string"
}

Start a new session reverification

Start a new session reverification flow by providing a verification level.

If the requested level equals 'secondFactor' or 'multiFactor' and the associated user doesn't have any available second factor, then we fallback to 'firstFactor'

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

the user session ID.

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

The level of authentication that the user needs to go through

Enum: "first_factor" "second_factor" "multi_factor"
Responses
200

Returns the session reverification object, as well as the session object.

401

Request was not successful

422

Request was not successful

post/v1/client/sessions/{session_id}/verify
Request samples
application/x-www-form-urlencoded
level=first_factor
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Prepare session reverification first factor

Prepare the first factor verification. 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.

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

the user session ID.

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

The strategy to be prepared for first factor authentication.

Enum: "email_code" "phone_code"
email_address_id
string or null

Used with the email_code strategy.

phone_number_id
string or null

Used with the phone_code strategy.

Responses
200

Returns the session reverification object, as well as the session object.

400

Request was not successful

403

Request was not successful

422

Request was not successful

post/v1/client/sessions/{session_id}/verify/prepare_first_factor
Request samples
application/x-www-form-urlencoded
strategy=email_code&email_address_id=string&phone_number_id=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Attempt session reverification first factor

Attempt the first factor verification. Requires the first factor verification to be prepared, unless you're using a password.

Parameter rules: If the strategy equals email_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
session_id
required
string

the user session ID.

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

The strategy to be used for first factor authentication.

Enum: "email_code" "password" "phone_code"
code
string or null

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

password
string or null

Used with the password strategy.

Responses
200

Returns the session reverification object, as well as the session object.

400

Request was not successful

403

Request was not successful

422

Request was not successful

post/v1/client/sessions/{session_id}/verify/attempt_first_factor
Request samples
application/x-www-form-urlencoded
strategy=email_code&code=string&password=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}

Prepare session reverification second factor

Prepare the second factor verification. Requires the status to be equal to needs_second_factor.

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

the user session ID.

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 session reverification object, as well as the session object.

400

Request was not successful

403

Request was not successful

422

Request was not successful

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

Attempt session reverification second factor

Attempt the second factor verification. Requires the 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
session_id
required
string

the user session ID.

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

The strategy to be attempted for second factor authentication.

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

Used with the phone_code, totp and backup_code strategies.

Responses
200

Returns the session reverification object, as well as the session object.

400

Request was not successful

403

Request was not successful

422

Request was not successful

post/v1/client/sessions/{session_id}/verify/attempt_second_factor
Request samples
application/x-www-form-urlencoded
strategy=phone_code&code=string
Response samples
application/json
{
  • "response": {
    },
  • "client": {
    }
}
➔ Next to Sign Ins