Clerk Backend API (v1)

Download OpenAPI specification:Download

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. 2021-02-05. For more information, please see Clerk API Versions.

Please see https://clerk.com/docs for more information.

Actor Tokens

Allow your users to sign in on behalf of other users.

Create actor token

Create an actor token that can be used to impersonate the given user. The actor parameter needs to include at least a "sub" key whose value is the ID of the actor (impersonating) user.

SecuritybearerAuth
Request
Request Body schema: application/json
user_id
required
string

The ID of the user being impersonated.

actor
required
object

The actor payload. It needs to include a sub property which should contain the ID of the actor. This whole payload will be also included in the JWT session token.

expires_in_seconds
integer
Default: 3600

Optional parameter to specify the life duration of the actor token in seconds. By default, the duration is 1 hour.

session_max_duration_in_seconds
integer
Default: 1800

The maximum duration that the session which will be created by the generated actor token should last. By default, the duration of a session created via an actor token, lasts 30 minutes.

Responses
200

Success

400

Request was not successful

402

Payment required

422

Invalid request parameters

post/actor_tokens
Request samples
application/json
{
  • "user_id": "string",
  • "actor": {
    },
  • "expires_in_seconds": 3600,
  • "session_max_duration_in_seconds": 1800
}
Response samples
application/json
{
  • "object": "actor_token",
  • "id": "string",
  • "status": "pending",
  • "user_id": "string",
  • "actor": { },
  • "token": "string",
  • "url": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Revoke actor token

Revokes a pending actor token.

SecuritybearerAuth
Request
path Parameters
actor_token_id
required
string

The ID of the actor token to be revoked.

Responses
200

Success

400

Request was not successful

404

Resource not found

post/actor_tokens/{actor_token_id}/revoke
Response samples
application/json
{
  • "object": "actor_token",
  • "id": "string",
  • "status": "pending",
  • "user_id": "string",
  • "actor": { },
  • "token": "string",
  • "url": "string",
  • "created_at": 0,
  • "updated_at": 0
}