openapi: 3.0.3
info:
  title: Clerk Backend Allowlist & Blocklist Users 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.
paths:
  /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
components:
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      description: Number of results to return (1-500, default 10).
      schema:
        type: integer
        default: 10
    Offset:
      name: offset
      in: query
      required: false
      description: Number of results to skip for pagination.
      schema:
        type: integer
        default: 0
    UserId:
      name: user_id
      in: path
      required: true
      description: The ID of the user.
      schema:
        type: string
  schemas:
    Metadata:
      type: object
      properties:
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        unsafe_metadata:
          type: object
          additionalProperties: true
    CreateUser:
      type: object
      properties:
        email_address:
          type: array
          items:
            type: string
        phone_number:
          type: array
          items:
            type: string
        username:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        password:
          type: string
        skip_password_checks:
          type: boolean
        public_metadata:
          type: object
          additionalProperties: true
    DeletedObject:
      type: object
      properties:
        object:
          type: string
        id:
          type: string
        deleted:
          type: boolean
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              long_message:
                type: string
              code:
                type: string
        clerk_trace_id:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        username:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        primary_email_address_id:
          type: string
          nullable: true
        banned:
          type: boolean
        locked:
          type: boolean
        two_factor_enabled:
          type: boolean
        public_metadata:
          type: object
          additionalProperties: true
        created_at:
          type: integer
        updated_at:
          type: integer
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Unauthorized:
      description: Missing or invalid Secret Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your Clerk instance Secret Key (starts with sk_test_ or sk_live_) passed as `Authorization: Bearer YOUR_SECRET_KEY`.'

Where this information came from

This is an independent, third-party profile of Clerk Users API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.

The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.

Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.

info@apievangelist.com · Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.