Clerk

Clerk Applications API

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.

GitHub OpenAPI

Operations 11

GET /platform/applications List Applications #
POST /platform/applications Create an Application #
GET /platform/applications/{applicationID} Get an Application #
PATCH /platform/applications/{applicationID} Update an Application #
DELETE /platform/applications/{applicationID} Delete an Application #
POST /platform/applications/{applicationID}/favicon Upload Application Favicon #
DELETE /platform/applications/{applicationID}/favicon Delete Application Favicon #
GET /platform/applications/{applicationID}/instances/{envOrInsID}/usage Get Instance Usage #
POST /platform/accountless_applications/claim Claim an Accountless Application #

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-applications-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/rules/clerk-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clerk-com-applications-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clerk-com-applications-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Platform Applications 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.
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}/instances/{envOrInsID}/usage:
    get:
      operationId: PlatformGetInstanceUsage
      x-speakeasy-group: platform
      x-speakeasy-name-override: getInstanceUsage
      tags:
      - Applications
      summary: Get Instance Usage
      description: 'Get usage totals for an application instance across meters such as MAU, MAO,

        SMS, custom domains, and enterprise connections.


        The `envOrInsID` parameter can be either an environment type (e.g., "development", "production")

        or an instance ID.


        Requires the `application_usage:read` scope.

        '
      security:
      - platform_api_access_token: []
      parameters:
      - name: applicationID
        in: path
        description: Application ID.
        required: true
        schema:
          type: string
      - name: envOrInsID
        in: path
        description: 'Environment type (e.g., "development", "production") or instance ID.

          '
        required: true
        schema:
          type: string
      - name: start
        in: query
        description: 'Start of the date range for usage data in YYYY-MM-DD format.

          Both `start` and `end` must be provided together.

          When omitted, the current billing cycle is used.

          '
        required: false
        schema:
          type: string
          format: date
      - name: end
        in: query
        description: 'Inclusive end of the date range for usage data in YYYY-MM-DD format.

          Both `start` and `end` must be provided together.

          When omitted, the current billing cycle is used.

          '
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Instance usage retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformInstanceUsageResponse'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /platform/accountless_applications/claim:
    post:
      operationId: PlatformClaimAccountlessApplication
      x-speakeasy-group: platform
      x-speakeasy-name-override: claimAccountlessApplication
      tags:
      - Applications
      summary: Claim an Accountless Application
      description: 'Claim an accountless application by assigning it to the authenticated principal''s workspace.

        The application is identified by a single-use claim token that was generated when the

        accountless application was created. Once claimed, the token is invalidated and cannot be reused.

        '
      security:
      - platform_api_access_token: []
      requestBody:
        description: Claim token and application name.
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                token:
                  type: string
                  description: The single-use claim token for the accountless application.
                name:
                  type: string
                  description: The name to assign to the claimed application.
                  maxLength: 50
              required:
              - token
              - name
      responses:
        '200':
          description: Application claimed 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'
components:
  responses:
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    InstanceUsageMeterWithBillable:
      title: Instance Usage Meter With Billable
      description: Usage totals for a meter that includes both total and billable quantities.
      type: object
      additionalProperties: false
      properties:
        total_usage:
          type: integer
          format: int64
          description: Total quantity for this meter in the selected period.
        total_billable_usage:
          type: integer
          format: int64
          description: Billable subset of total usage for this meter in the selected period.
      required:
      - total_usage
      - total_billable_usage
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    PlatformApplicationInstance:
      title: Application Instance
      description: Represents an instance (environment) within a Clerk application. Each application can have multiple instances, typically one for development and one for production.
      type: object
      additionalProperties: false
      properties:
        instance_id:
          type: string
          description: The unique identifier for this instance. Use this ID when making API calls that target a specific instance.
          example: ins_2abc123def456
        environment_type:
          type: string
          description: The environment type of the instance. Determines whether this instance is used for development/testing or production workloads.
          enum:
          - development
          - production
          example: production
        secret_key:
          type: string
          description: The secret key for authenticating server-side API requests to this instance. Keep this value secure and never expose it in client-side code.
          example: sk_live_abc123...
          x-sensitive: true
        publishable_key:
          type: string
          description: The publishable key for this instance. Safe to include in client-side code and used to initialize Clerk SDKs in the browser.
          example: pk_live_abc123...
      required:
      - instance_id
      - environment_type
    PlatformDeletedObjectResponse:
      type: object
      additionalProperties: false
      properties:
        deleted:
          type: boolean
          description: Whether the object was deleted.
        object:
          type: string
          example: deleted
        id:
          type: string
          description: The ID of the deleted resource.
      required:
      - deleted
      - object
      - id
    InstanceSMSUsage:
      title: Instance SMS Usage
      description: Total SMS usage with per-geographic-tier breakdowns.
      type: object
      additionalProperties: false
      properties:
        total_usage:
          type: integer
          format: int64
          description: Total SMS messages across all tiers.
        tier_a:
          $ref: '#/components/schemas/InstanceUsageMeter'
        tier_b:
          $ref: '#/components/schemas/InstanceUsageMeter'
        tier_c:
          $ref: '#/components/schemas/InstanceUsageMeter'
        tier_d:
          $ref: '#/components/schemas/InstanceUsageMeter'
        tier_e:
          $ref: '#/components/schemas/InstanceUsageMeter'
        tier_f:
          $ref: '#/components/schemas/InstanceUsageMeter'
      required:
      - total_usage
      - tier_a
      - tier_b
      - tier_c
      - tier_d
      - tier_e
      - tier_f
    PlatformUpdateApplicationRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the application.
    InstanceUsageMeter:
      title: Instance Usage Meter
      description: Usage totals for a single meter.
      type: object
      additionalProperties: false
      properties:
        total_usage:
          type: integer
          format: int64
          description: Total quantity for this meter in the selected period.
      required:
      - total_usage
    PlatformInstanceUsageResponse:
      title: Instance Usage Report
      description: Usage report for an application instance containing per-meter totals.
      type: object
      additionalProperties: false
      properties:
        application_id:
          type: string
          description: The ID of the application.
        instance_id:
          type: string
          description: The ID of the instance.
        period_start:
          type: string
          format: date-time
          description: 'Inclusive start of the usage period boundary (RFC3339). When an

            explicit date range is provided, this is midnight UTC on the start

            date. When no date range is provided, this is the start of the

            current billing cycle.

            '
        period_end:
          type: string
          format: date-time
          description: 'Exclusive end of the usage period boundary (RFC3339). When an

            explicit date range is provided, this is midnight UTC immediately

            after the requested end date. When no date range is provided, this

            is the end of the current billing cycle.

            '
        mau:
          $ref: '#/components/schemas/InstanceUsageMeterWithBillable'
        mao:
          $ref: '#/components/schemas/InstanceUsageMeterWithBillable'
        custom_domains:
          $ref: '#/components/schemas/InstanceUsageMeter'
        sms_messages:
          $ref: '#/components/schemas/InstanceSMSUsage'
        enterprise_connections:
          $ref: '#/components/schemas/InstanceUsageMeter'
      required:
      - application_id
      - instance_id
      - period_start
      - period_end
      - mau
      - mao
      - custom_domains
      - sms_messages
      - enterprise_connections
    PlatformApplicationResponse:
      type: object
      additionalProperties: false
      properties:
        application_id:
          type: string
          description: The ID of the application.
        name:
          type: string
          description: The name of the application.
        instances:
          type: array
          description: List of instances associated with this application.
          items:
            $ref: '#/components/schemas/PlatformApplicationInstance'
      required:
      - application_id
      - name
      - instances
    PlatformListApplicationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/PlatformApplicationResponse'
      minItems: 0
    PlatformCreateApplicationRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the application.
        domain:
          type: string
          description: The domain for the application (optional).
        proxy_path:
          type: string
          description: Custom proxy path for provider domains (e.g., "/__clerk"). Must start with a leading slash and be a single path segment. Defaults to "/__clerk" if not provided.
        environment_types:
          type: array
          items:
            type: string
          description: List of environment types to create instances for. Accepted values are "development" and "production". Defaults to "development" if not provided.
        template:
          type: string
          description: Application template to use for configuring the application (e.g., "b2b-saas", "b2c-saas", "waitlist").
      required:
      - name
  securitySchemes:
    platform_api_access_token:
      type: http
      scheme: bearer
      description: Platform API access token.
externalDocs:
  url: https://clerk.com/docs
x-tagGroups:
- name: Core Resources
  tags:
  - Applications
  - Domains
  - Application Transfers
  - Users
  - JWT Templates
  - Redirect URLs
  - Config