The Clerk Platform API (beta) is a partner / reseller surface for programmatically creating and managing Clerk applications, domains, application transfers, users, JWT templates, redirect URLs, and platform configuration on behalf of end customers.
openapi: 3.0.3
info:
title: Clerk Platform 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 Platform API, for programmatic management of resources of a workspace.
> [!note]
> This API is currently in private beta. If you''d like access for your workspace, please fill out and submit our [request form](https://clerkdev.notion.site/2df2b9ab44fe803f9031e9f3185c5e19).'
version: BETA
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:
- platform_api_access_token: []
tags:
- name: Applications
description: An object representing a Clerk application. Each `application` can have multiple `instances`, typically one for development and one for production, each with distinct user pools.
- name: Domains
description: An object representing a domain associated with a Clerk application. In development `instances`, a domain is provided by Clerk. Production `instances` require additional configuration to be set up.
- name: Application Transfers
description: 'An object representing a transfer request for an application between workspaces.
The high-level flow for application transfer:
1. The initial workspace can create an application transfer. A single-use `code` will be generated which may be distributed to any end-user of Clerk.
2. The code must be claimed through the clerk dashboard: https://dashboard.clerk.com/apps/transfer?code=<...>
Note that once a transfer is claimed, the original workspace will no longer have access to the application.'
- name: Users
description: Operations for managing users within an application instance.
- name: JWT Templates
description: Operations for managing JWT templates within an application instance.
- name: Redirect URLs
description: Operations for managing redirect URLs within an application instance.
- name: Config
description: Operations for managing instance configuration. The config API provides a unified interface for reading and updating instance settings, including authentication methods, SSO connections, and other instance-level configuration options.
externalDocs:
url: https://clerk.com/docs
paths:
/platform/applications:
get:
operationId: PlatformListApplications
x-speakeasy-group: platform
x-speakeasy-name-override: listApplications
tags:
- Applications
summary: List Applications
description: 'List applications.
'
security:
- platform_api_access_token: []
parameters:
- name: include_secret_keys
in: query
description: Whether to include secret keys in the response.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Applications retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformListApplicationsResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
post:
operationId: PlatformCreateApplication
x-speakeasy-group: platform
x-speakeasy-name-override: createApplication
tags:
- Applications
summary: Create an Application
description: 'Create a new application.
'
security:
- platform_api_access_token: []
requestBody:
description: Application data to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformCreateApplicationRequest'
responses:
'200':
description: Application created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/applications/{applicationID}:
get:
operationId: PlatformGetApplication
x-speakeasy-group: platform
x-speakeasy-name-override: getApplication
tags:
- Applications
summary: Get an Application
description: 'Get application details.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: include_secret_keys
in: query
description: Whether to include secret keys in the response. If 'true', the response will include the secret keys for each instance.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: Application retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
patch:
operationId: PlatformUpdateApplication
x-speakeasy-group: platform
x-speakeasy-name-override: updateApplication
tags:
- Applications
summary: Update an Application
description: 'Update an application.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
requestBody:
description: Application data to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformUpdateApplicationRequest'
responses:
'200':
description: Application updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
operationId: PlatformDeleteApplication
x-speakeasy-group: platform
x-speakeasy-name-override: deleteApplication
tags:
- Applications
summary: Delete an Application
description: 'Delete an application.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
responses:
'200':
description: Application deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDeletedObjectResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
/platform/applications/{applicationID}/logo:
post:
operationId: PlatformUploadApplicationLogo
x-speakeasy-group: platform
x-speakeasy-name-override: uploadApplicationLogo
tags:
- Applications
summary: Upload Application Logo
description: 'Set or replace an application''s logo by uploading an image file.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
application/octet-stream:
schema:
type: string
example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
responses:
'200':
description: Application logo uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'413':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
operationId: PlatformDeleteApplicationLogo
x-speakeasy-group: platform
x-speakeasy-name-override: deleteApplicationLogo
tags:
- Applications
summary: Delete Application Logo
description: 'Delete an application''s logo.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
responses:
'200':
description: Application logo deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
/platform/applications/{applicationID}/favicon:
post:
operationId: PlatformUploadApplicationFavicon
x-speakeasy-group: platform
x-speakeasy-name-override: uploadApplicationFavicon
tags:
- Applications
summary: Upload Application Favicon
description: 'Set or replace an application''s favicon by uploading an image file.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
application/octet-stream:
schema:
type: string
example: data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAGAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAA
responses:
'200':
description: Application favicon uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'413':
$ref: '#/components/responses/ClerkErrors'
'422':
$ref: '#/components/responses/UnprocessableEntity'
delete:
operationId: PlatformDeleteApplicationFavicon
x-speakeasy-group: platform
x-speakeasy-name-override: deleteApplicationFavicon
tags:
- Applications
summary: Delete Application Favicon
description: 'Delete an application''s favicon.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
responses:
'200':
description: Application favicon deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
/platform/applications/{applicationID}/domain:
patch:
operationId: PlatformUpdateApplicationDomain
x-speakeasy-group: platform
x-speakeasy-name-override: updateApplicationDomain
tags:
- Domains
summary: Update Application Domain
description: 'Update the production domain for an application.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
requestBody:
description: Domain data to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformUpdateApplicationDomainRequest'
responses:
'200':
description: Application domain updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDomainResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/applications/{applicationID}/domains:
get:
operationId: PlatformListApplicationDomains
x-speakeasy-group: platform
x-speakeasy-name-override: listApplicationDomains
tags:
- Domains
summary: List Application Domains
description: 'List all domains for an application''s production instance.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
responses:
'200':
description: Application domains retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformListApplicationDomainsResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
post:
operationId: PlatformCreateApplicationDomain
x-speakeasy-group: platform
x-speakeasy-name-override: createApplicationDomain
tags:
- Domains
summary: Create Application Domain
description: 'Create a provider domain for an application''s production instance.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
requestBody:
description: Domain data to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformCreateApplicationDomainRequest'
responses:
'201':
description: Application domain created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDomainResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/applications/{applicationID}/domains/{domainIDOrName}:
get:
operationId: PlatformGetApplicationDomain
x-speakeasy-group: platform
x-speakeasy-name-override: getApplicationDomain
tags:
- Domains
summary: Get Application Domain
description: 'Get domain information for an application.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: domainIDOrName
in: path
description: Domain ID or domain name.
example: dmn_abcdefghijklmnopqrstuvwxyz0
required: true
schema:
type: string
responses:
'200':
description: Application domain retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDomainResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
delete:
operationId: PlatformDeleteApplicationDomain
x-speakeasy-group: platform
x-speakeasy-name-override: deleteApplicationDomain
tags:
- Domains
summary: Delete Application Domain
description: 'Delete a provider domain from an application''s production instance.
Only provider domains can be deleted. The primary domain cannot be deleted.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: domainIDOrName
in: path
description: Domain ID or domain name.
example: dmn_abcdefghijklmnopqrstuvwxyz0
required: true
schema:
type: string
responses:
'200':
description: Application domain deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDeletedObjectResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/applications/{applicationID}/domains/{domainIDOrName}/status:
get:
operationId: PlatformGetApplicationDomainStatus
x-speakeasy-group: platform
x-speakeasy-name-override: getApplicationDomainStatus
tags:
- Domains
summary: Get Application Domain Status
description: 'Get the status of a domain for an application.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: domainIDOrName
in: path
description: Domain ID or domain name.
example: dmn_abcdefghijklmnopqrstuvwxyz0
required: true
schema:
type: string
responses:
'200':
description: Application domain status retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDomainStatusResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
/platform/applications/{applicationID}/domains/{domainIDOrName}/dns_check:
post:
operationId: PlatformTriggerDNSCheck
x-speakeasy-group: platform
x-speakeasy-name-override: triggerDNSCheck
tags:
- Domains
summary: Trigger DNS Check
description: 'Triggers a DNS check for a domain and returns the current domain status.
This endpoint ensures that at most one DNS check job is in-flight at any time.
If a check is already running or was recently performed, a 409 Conflict is returned.
Use this endpoint to trigger a new DNS verification check after configuring DNS records.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: domainIDOrName
in: path
description: Domain ID or domain name.
example: dmn_abcdefghijklmnopqrstuvwxyz0
required: true
schema:
type: string
responses:
'200':
description: DNS check triggered and domain status returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformDNSCheckResponse'
'400':
$ref: '#/components/responses/ClerkErrors'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
'409':
$ref: '#/components/responses/Conflict'
/platform/domains:
get:
operationId: PlatformListDomains
x-speakeasy-group: platform
x-speakeasy-name-override: listDomains
tags:
- Domains
summary: List Domains
description: 'List production instance domains for applications in the authenticated workspace.
Results are sorted by domain creation time in descending order (most recent first).
Set `include_development` to include development instance domains.
'
security:
- platform_api_access_token: []
parameters:
- name: name
in: query
description: Filter domains whose name contains this substring (case-insensitive).
required: false
schema:
type: string
- name: include_development
in: query
description: When `true`, include development instance domains. Defaults to production only.
required: false
schema:
type: string
enum:
- 'true'
- name: limit
in: query
description: Number of results to return per page (1-500, default 10).
required: false
schema:
type: integer
minimum: 1
maximum: 500
default: 10
- name: starting_after
in: query
description: 'Cursor for pagination. Provide the ID of the last domain from the
previous page to get the next page of results.
'
required: false
schema:
type: string
- name: ending_before
in: query
description: 'Cursor for pagination. Provide the ID of the first domain from the
previous page to get the previous page of results.
'
required: false
schema:
type: string
responses:
'200':
description: Domains retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformListDomainsResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/domains/{domainIDOrName}:
get:
operationId: PlatformGetDomain
x-speakeasy-group: platform
x-speakeasy-name-override: getDomain
tags:
- Domains
summary: Get Domain
description: 'Retrieve a single domain by ID or name for the authenticated workspace.
'
security:
- platform_api_access_token: []
parameters:
- name: domainIDOrName
in: path
description: Domain ID or domain name.
example: dmn_abcdefghijklmnopqrstuvwxyz0
required: true
schema:
type: string
responses:
'200':
description: Domain retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformWorkspaceDomainResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
/platform/application_transfers:
get:
operationId: PlatformListApplicationTransfers
x-speakeasy-group: platform
x-speakeasy-name-override: listApplicationTransfers
tags:
- Application Transfers
summary: List Application Transfers
description: 'List all transfer requests created by the authenticated workspace. Returns
transfers sorted by creation date in descending order (most recent first).
Use the `status` parameter to filter by transfer status.
'
security:
- platform_api_access_token: []
parameters:
- name: status
in: query
description: 'Filter by transfer status. Multiple values can be provided by repeating
the parameter (e.g., `?status=pending&status=canceled`).
'
required: false
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- pending
- completed
- canceled
- expired
- name: limit
in: query
description: Number of results to return per page (1-500, default 10).
required: false
schema:
type: integer
minimum: 1
maximum: 500
default: 10
- name: starting_after
in: query
description: 'Cursor for pagination. Provide the ID of the last transfer from the
previous page to get the next page of results.
'
required: false
schema:
type: string
- name: ending_before
in: query
description: 'Cursor for pagination. Provide the ID of the first transfer from the
previous page to get the previous page of results.
'
required: false
schema:
type: string
responses:
'200':
description: Application transfers retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformListApplicationTransfersResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/platform/applications/{applicationID}/transfers:
post:
operationId: PlatformCreateApplicationTransfer
x-speakeasy-group: platform
x-speakeasy-name-override: createApplicationTransfer
tags:
- Application Transfers
summary: Create an Application Transfer
description: 'Create a new transfer request for an application. This initiates the process of
transferring ownership of the application to another workspace.
Only one pending transfer can exist for an application at a time. The transfer
will expire after 24 hours if not completed.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
responses:
'201':
description: Application transfer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationTransferResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'409':
$ref: '#/components/responses/Conflict'
/platform/applications/{applicationID}/transfers/{transferID}:
get:
operationId: PlatformGetApplicationTransfer
x-speakeasy-group: platform
x-speakeasy-name-override: getApplicationTransfer
tags:
- Application Transfers
summary: Get an Application Transfer
description: 'Retrieve details of an application transfer by its ID.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: transferID
in: path
description: Application Transfer ID.
required: true
schema:
type: string
responses:
'200':
description: Application transfer retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationTransferResponse'
'401':
$ref: '#/components/responses/AuthenticationInvalid'
'403':
$ref: '#/components/responses/AuthorizationInvalid'
'404':
$ref: '#/components/responses/ResourceNotFound'
delete:
operationId: PlatformCancelApplicationTransfer
x-speakeasy-group: platform
x-speakeasy-name-override: cancelApplicationTransfer
tags:
- Application Transfers
summary: Cancel an Application Transfer
description: 'Cancel an existing application transfer. Only transfers in ''pending'' status can be canceled.
'
security:
- platform_api_access_token: []
parameters:
- name: applicationID
in: path
description: Application ID.
required: true
schema:
type: string
- name: transferID
in: path
description: Application Transfer ID.
required: true
schema:
type: string
responses:
'200':
description: Application transfer canceled successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformApplicationTrans
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-platform-api-openapi.yml