openapi: 3.0.3 info: title: Clerk Backend Account Portal API Keys API x-logo: url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75 altText: Clerk docs href: https://clerk.com/docs contact: email: support@clerk.com name: Clerk Platform Team url: https://clerk.com/support description: '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. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions). Please see https://clerk.com/docs for more information.' version: '2025-11-10' termsOfService: https://clerk.com/terms license: name: MIT url: https://github.com/clerk/openapi-specs/blob/main/LICENSE servers: - url: https://api.clerk.com/v1 security: - bearerAuth: [] tags: - name: API Keys description: Endpoints for managing API Keys paths: /api_keys: post: operationId: createApiKey summary: Create an API Key tags: - API Keys requestBody: required: true content: application/json: schema: type: object properties: type: type: string minLength: 3 maxLength: 25 default: api_key name: type: string minLength: 3 pattern: ^(\S(.*\S)?)?$ description: type: string nullable: true maxLength: 255 subject: type: string pattern: ^(user|org|mch|scim)_\w{27}$ claims: nullable: true scopes: type: array items: type: string default: [] created_by: type: string nullable: true pattern: ^user_\w{27}$ seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true required: - name - subject additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write secret: type: string example: ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - secret - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '409': description: 409 Conflict content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors get: operationId: getApiKeys summary: Get API Keys tags: - API Keys parameters: - schema: type: string minLength: 3 default: api_key required: false name: type in: query - schema: type: string pattern: ^(user|org|mch|scim)_\w{27}$ required: true name: subject in: query - schema: type: string enum: - 'true' - 'false' default: 'false' required: false name: include_invalid in: query - schema: type: number minimum: 1 maximum: 100 default: 10 required: false name: limit in: query - schema: type: number nullable: true minimum: 0 default: 0 required: false name: offset in: query - schema: type: string required: false name: query in: query responses: '200': description: 200 OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false total_count: type: number required: - data - total_count '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}: get: operationId: getApiKey summary: Get an API Key by ID tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors patch: operationId: updateApiKey summary: Update an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path requestBody: required: true content: application/json: schema: type: object properties: claims: nullable: true scopes: type: array items: type: string description: type: string nullable: true maxLength: 255 subject: type: string pattern: ^(user|org|mch|scim)_\w{27}$ seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors delete: operationId: deleteApiKey summary: Delete an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: id: type: string example: ak_3beecc9c60adb5f9b850e91a8ee1e992 object: type: string enum: - api_key deleted: type: boolean enum: - true required: - id - object - deleted '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}/secret: get: operationId: getApiKeySecret summary: Get an API Key Secret tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: secret: type: string required: - secret '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}/revoke: post: operationId: revokeApiKey summary: Revoke an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path requestBody: required: true content: application/json: schema: type: object properties: revocation_reason: type: string nullable: true additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/verify: post: operationId: verifyApiKey summary: Verify an API Key tags: - API Keys requestBody: required: true content: application/json: schema: type: object properties: secret: type: string required: - secret additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors components: securitySchemes: bearerAuth: type: http scheme: bearer description: Secret key, obtained under "API Keys" in the Clerk Dashboard. bearerFormat: sk__ externalDocs: url: https://clerk.com/docs x-speakeasy-retries: strategy: backoff backoff: initialInterval: 500 maxInterval: 60000 maxElapsedTime: 3600000 exponent: 1.5 statusCodes: - 5XX retryConnectionErrors: true