Clerk Sessions API

openapi: 3.0.3
info:
  title: Clerk Backend API
  description: >-
    The Clerk Backend API manages Clerk's authentication and user management
    resources server-side: users, organizations and memberships, sessions,
    clients, sign-ups, JWT templates, JWKS, email/SMS verification and templates,
    allowlist/blocklist identifiers, invitations, SAML/enterprise connections,
    OAuth applications, and Svix-powered webhooks. The base URL is
    https://api.clerk.com/v1 and every request (except GET /jwks and the public
    interstitial) is authenticated with your instance Secret Key passed as
    `Authorization: Bearer sk_...`. This description is grounded in Clerk's
    published OpenAPI spec (github.com/clerk/openapi-specs, bapi) but is a
    curated subset covering the primary resource groups; it does not enumerate
    every parameter or schema property. Verify the current version-dated spec on
    GitHub for the authoritative contract.
  version: '2026-05-12'
  contact:
    name: Clerk
    url: https://clerk.com
  license:
    name: Clerk Documentation
    url: https://clerk.com/docs
servers:
  - url: https://api.clerk.com/v1
    description: Clerk Backend API
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Create and manage users and their identities.
  - name: Organizations
    description: Multi-tenant organizations.
  - name: Organization Memberships
    description: Members of an organization and their roles.
  - name: Organization Invitations
    description: Invitations to join an organization.
  - name: Sessions
    description: User sessions and session tokens.
  - name: Clients
    description: Browser / device clients tracking active sessions.
  - name: Sign-ups & Tokens
    description: Sign-up attempts, sign-in tokens, and actor tokens.
  - name: JWT Templates
    description: Named claim templates for custom session tokens.
  - name: JWKS
    description: Public keys for verifying Clerk-issued JWTs.
  - name: Email & SMS
    description: Email addresses, phone numbers, and message templates.
  - name: Allowlist & Blocklist
    description: Identifiers permitted or denied from signing up.
  - name: Invitations
    description: Application-level sign-up invitations.
  - name: SAML & Enterprise Connections
    description: Enterprise SSO connections.
  - name: OAuth Applications
    description: OAuth applications where Clerk is the identity provider.
  - name: Webhooks
    description: Svix-powered webhook portal management.
paths:
  # ---------------- Users ----------------
  /users:
    get:
      operationId: getUserList
      tags: [Users]
      summary: List all users
      description: Returns a list of users, filterable and paginated with limit/offset and query parameters.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      tags: [Users]
      summary: Create a user
      description: Creates a new user. Your instance must be configured for the identifiers supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '200':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /users/count:
    get:
      operationId: getUsersCount
      tags: [Users]
      summary: Count users
      description: Returns a total count of users matching the given filters.
      responses:
        '200':
          description: The total user count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                  total_count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{user_id}:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUser
      tags: [Users]
      summary: Retrieve a user
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateUser
      tags: [Users]
      summary: Update a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      tags: [Users]
      summary: Delete a user
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedObject'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{user_id}/ban:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: banUser
      tags: [Users]
      summary: Ban a user
      description: Marks the user as banned, preventing them from signing in.
      responses:
        '200':
          description: The banned user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}/unban:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: unbanUser
      tags: [Users]
      summary: Unban a user
      responses:
        '200':
          description: The unbanned user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}/lock:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: lockUser
      tags: [Users]
      summary: Lock a user
      responses:
        '200':
          description: The locked user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}/unlock:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: unlockUser
      tags: [Users]
      summary: Unlock a user
      responses:
        '200':
          description: The unlocked user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}/metadata:
    parameters:
      - $ref: '#/components/parameters/UserId'
    patch:
      operationId: updateUserMetadata
      tags: [Users]
      summary: Merge and update user metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}/verify_password:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: verifyPassword
      tags: [Users]
      summary: Verify a user's password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
  # ---------------- Organizations ----------------
  /organizations:
    get:
      operationId: listOrganizations
      tags: [Organizations]
      summary: List all organizations
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A list of organizations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  total_count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOrganization
      tags: [Organizations]
      summary: Create an organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganization'
      responses:
        '200':
          description: The created organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '422':
          $ref: '#/components/responses/ValidationError'
  /organizations/{organization_id}:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: getOrganization
      tags: [Organizations]
      summary: Retrieve an organization
      responses:
        '200':
          description: The requested organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateOrganization
      tags: [Organizations]
      summary: Update an organization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
    delete:
      operationId: deleteOrganization
      tags: [Organizations]
      summary: Delete an organization
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedObject'
  /organizations/{organization_id}/metadata:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
    patch:
      operationId: mergeOrganizationMetadata
      tags: [Organizations]
      summary: Merge and update organization metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: The updated organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
  # ---------------- Organization Memberships ----------------
  /organizations/{organization_id}/memberships:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: listOrganizationMemberships
      tags: [Organization Memberships]
      summary: List organization memberships
      responses:
        '200':
          description: A list of organization memberships.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationMembership'
                  total_count:
                    type: integer
    post:
      operationId: createOrganizationMembership
      tags: [Organization Memberships]
      summary: Create an organization membership
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, role]
              properties:
                user_id:
                  type: string
                role:
                  type: string
      responses:
        '200':
          description: The created membership.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMembership'
  /organizations/{organization_id}/memberships/{user_id}:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/UserId'
    patch:
      operationId: updateOrganizationMembership
      tags: [Organization Memberships]
      summary: Update an organization membership role
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role:
                  type: string
      responses:
        '200':
          description: The updated membership.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMembership'
    delete:
      operationId: deleteOrganizationMembership
      tags: [Organization Memberships]
      summary: Remove a member from an organization
      responses:
        '200':
          description: The removed membership.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMembership'
  # ---------------- Organization Invitations ----------------
  /organizations/{organization_id}/invitations:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: listOrganizationInvitations
      tags: [Organization Invitations]
      summary: List organization invitations
      responses:
        '200':
          description: A list of organization invitations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrganizationInvitation'
    post:
      operationId: createOrganizationInvitation
      tags: [Organization Invitations]
      summary: Create an organization invitation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email_address, role]
              properties:
                email_address:
                  type: string
                role:
                  type: string
                inviter_user_id:
                  type: string
                redirect_url:
                  type: string
      responses:
        '200':
          description: The created invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitation'
  /organizations/{organization_id}/invitations/bulk:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
    post:
      operationId: createOrganizationInvitationBulk
      tags: [Organization Invitations]
      summary: Bulk create organization invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                additionalProperties: true
      responses:
        '200':
          description: The created invitations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationInvitation'
  /organizations/{organization_id}/invitations/{invitation_id}/revoke:
    parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - name: invitation_id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: revokeOrganizationInvitation
      tags: [Organization Invitations]
      summary: Revoke a pending organization invitation
      responses:
        '200':
          description: The revoked invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitation'
  # ---------------- Sessions ----------------
  /sessions:
    get:
      operationId: getSessionList
      tags: [Sessions]
      summary: List all sessions
      parameters:
        - name: user_id
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of sessions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Session'
    post:
      operationId: createSession
      tags: [Sessions]
      summary: Create a session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
      responses:
        '200':
          description: The created session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /sessions/{session_id}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    get:
      operationId: getSession
      tags: [Sessions]
      summary: Retrieve a session
      responses:
        '200':
          description: The requested session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          $ref: '#/components/responses/NotFound'
  /sessions/{session_id}/revoke:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: revokeSession
      tags: [Sessions]
      summary: Revoke a session
      responses:
        '200':
          description: The revoked session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
  /sessions/{session_id}/tokens:
    parameters:
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: createSessionToken
      tags: [Sessions]
      summary: Create a session token
      description: Mints a short-lived session JWT for the given session.
      responses:
        '200':
          description: The generated token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionToken'
  /sessions/{session_id}/tokens/{template_name}:
    parameters:
      - $ref: '#/components/parameters/SessionId'
      - name: template_name
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: createSessionTokenFromTemplate
      tags: [Sessions]
      summary: Create a session token from a JWT template
      description: Mints a session token whose claims are shaped by the named JWT template.
      responses:
        '200':
          description: The generated token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionToken'
  # ---------------- Clients ----------------
  /clients:
    get:
      operationId: getClientList
      tags: [Clients]
      summary: List all clients
      responses:
        '200':
          description: A list of clients.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'
  /clients/verify:
    post:
      operationId: verifyClient
      tags: [Clients]
      summary: Verify a client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
      responses:
        '200':
          description: The verified client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
  /clients/{client_id}:
    parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getClient
      tags: [Clients]
      summary: Retrieve a client
      responses:
        '200':
          description: The requested client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '404':
          $ref: '#/components/responses/NotFound'
  # ---------------- Sign-ups & Tokens ----------------
  /sign_ups/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getSignUp
      tags: [Sign-ups & Tokens]
      summary: Retrieve a sign-up
      responses:
        '200':
          description: The requested sign-up attempt.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    patch:
      operationId: updateSignUp
      tags: [Sign-ups & Tokens]
      summary: Update a sign-up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated sign-up attempt.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /sign_in_tokens:
    post:
      operationId: createSignInToken
      tags: [Sign-ups & Tokens]
      summary: Create a sign-in token
      description: Creates a single-use, time-limited token that authenticates a user without a password.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id]
              properties:
                user_id:
                  type: string
                expires_in_seconds:
                  type: integer
      responses:
        '200':
          description: The created sign-in token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInToken'
  /sign_in_tokens/{sign_in_token_id}/revoke:
    parameters:
      - name: sign_in_token_id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: revokeSignInToken
      tags: [Sign-ups & Tokens]
      summary: Revoke a sign-in token
      responses:
        '200':
          description: The revoked sign-in token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInToken'
  /actor_tokens:
    post:
      operationId: createActorToken
      tags: [Sign-ups & Tokens]
      summary: Create an actor token
      description: Creates a token allowing an actor (impersonator) to sign in as another user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, actor]
              properties:
                user_id:
                  type: string
                actor:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The created actor token.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /actor_tokens/{actor_token_id}/revoke:
    parameters:
      - name: actor_token_id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: revokeActorToken
      tags: [Sign-ups & Tokens]
      summary: Revoke an actor token
      responses:
        '200':
          description: The revoked actor token.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  # ---------------- JWT Templates ----------------
  /jwt_templates:
    get:
      operationId: listJWTTemplates
      tags: [JWT Templates]
      summary: List all JWT templates
      responses:
        '200':
          description: A list of JWT templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JWTTemplate'
    post:
      operationId: createJWTTemplate
      tags: [JWT Templates]
      summary: Create a JWT template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJWTTemplate'
      responses:
        '200':
          description: The created JWT template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTTemplate'
  /jwt_templates/{template_id}:
    parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getJWTTemplate
      tags: [JWT Templates]
      summary: Retrieve a JWT template
      responses:
        '200':
          description: The requested JWT template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTTemplate'
    patch:
      operationId: updateJWTTemplate
      tags: [JWT Templates]
      summary: Update a JWT template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJWTTemplate'
      responses:
        '200':
          description: The updated JWT template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTTemplate'
    delete:
      operationId: deleteJWTTemplate
      tags: [JWT Templates]
      summary: Delete a JWT template
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedObject'
  # ---------------- JWKS ----------------
  /jwks:
    get:
      operationId: getJWKS
      tags: [JWKS]
      summary: Retrieve the JSON Web Key Set
      description: >-
        Returns the JSON Web Key Set of public keys used to verify Clerk-issued
        JWT signatures. This endpoint is unauthenticated and not rate limited.
      security: []
      responses:
        '200':
          description: The JWKS document.
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
  # ---------------- Email & SMS ----------------
  /email_addresses:
    post:
      operationId: createEmailAddress
      tags: [Email & SMS]
      summary: Create an email address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, email_address]
              properties:
                user_id:
                  type: string
                email_address:
                  type: string
                verified:
                  type: boolean
                primary:
                  type: boolean
      responses:
        '200':
          description: The created email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'
  /email_addresses/{email_address_id}:
    parameters:
      - name: email_address_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getEmailAddress
      tags: [Email & SMS]
      summary: Retrieve an email address
      responses:
        '200':
          description: The requested email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddress'
    delete:
      operationId: deleteEmailAddress
      tags: [Email & SMS]
      summary: Delete an email address
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedObject'
  /phone_numbers:
    post:
      operationId: createPhoneNumber
      tags: [Email & SMS]
      summary: Create a phone number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, phone_number]
              properties:
                user_id:
                  type: string
                phone_number:
                  type: string
                verified:
                  type: boolean
      responses:
        '200':
          description: The created phone number.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /templates/{template_type}:
    parameters:
      - name: template_type
        in: path
        required: true
        description: Either "email" or "sms".
        schema:
          type: string
          enum: [email, sms]
    get:
      operationId: listTemplates
      tags: [Email & SMS]
      summary: List templates
      responses:
        '200':
          description: A list of message templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /templates/{template_type}/{slug}:
    parameters:
      - name: template_type
        in: path
        required: true
        schema:
          type: string
          enum: [email, sms]
      - name: slug
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getTemplate
      tags: [Email & SMS]
      summary: Retrieve a template
      responses:
        '200':
          description: The requested template.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      operationId: upsertTemplate
      tags: [Email & SMS]
      summary: Update a template
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated template.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  # ---------------- Allowlist & Blocklist ----------------
  /allowlist_identifiers:
    get:
      operationId: listAllowlistIdentifiers
      tags: [Allowlist & Blocklist]
      summary: List all allowli

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-dev/refs/heads/main/openapi/clerk-dev-openapi.yml