Clerk docs

Clerk Backend API (v1)

Download OpenAPI specification:Download

Clerk Platform Team: support@clerk.com URL: https://clerk.com/support License: MIT Terms of Service

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.

https://clerk.com/docs

Actor Tokens

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

https://clerk.com/docs/authentication/user-impersonation#actor-tokens

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 that can use the newly created sign in token.

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
}
➔ Next to Allow-list / Block-list