Clerk OAuth Applications API

openapi: 3.2.0
info:
  title: Clerk Backend OAuth 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 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.


    Please see https://clerk.com/docs for more information.'
  version: '2026-08-20'
  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: OAuth Applications
  description: OAuth applications contain data for clients using Clerk as an OAuth2 identity provider.
paths:
  /oauth_applications:
    get:
      operationId: ListOAuthApplications
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: list
      summary: Get a list of OAuth applications for an instance
      description: 'This request returns the list of OAuth applications for an instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.

        The OAuth applications are ordered by descending creation date.

        Most recent OAuth applications will be returned first.'
      tags:
      - OAuth Applications
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - name: order_by
        in: query
        description: 'Allows to return OAuth applications in a particular order.

          At the moment, you can order the returned OAuth applications by their `created_at` and `name`.

          In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.

          For example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example,

          if you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case.'
        required: false
        schema:
          type: string
          default: +created_at
      - name: name_query
        in: query
        description: 'Returns OAuth applications with names that match the given query, via case-insensitive partial match.

          Also returns the OAuth application whose `client_id` is exactly the given query, which is useful for

          resolving a `client_id` to the OAuth application `id` required by the read, update and delete endpoints.'
        required: false
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplications'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateOAuthApplication
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: create
      summary: Create an OAuth application
      description: 'Creates a new OAuth application with the given name and callback URL for an instance.

        The callback URL must be a valid URL.

        All URL schemes are allowed such as `http://`, `https://`, `myapp://`, etc...'
      tags:
      - OAuth Applications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'The name of the new OAuth application.

                    Max length: 256'
                redirect_uris:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: An array of redirect URIs of the new OAuth application
                callback_url:
                  type:
                  - string
                  - 'null'
                  maxLength: 1024
                  description: The callback URL of the new OAuth application
                  deprecated: true
                scopes:
                  type:
                  - string
                  - 'null'
                  maxLength: 1024
                  description: Define the application's built-in and custom scope ceiling. Provide scope keys as a space-delimited string. Custom keys must exist in the instance OAuth scope catalog.
                  default: profile email
                  example: profile email public_metadata
                consent_screen_enabled:
                  type:
                  - boolean
                  - 'null'
                  default: true
                  description: True to enable a consent screen to display in the authentication flow.
                pkce_required:
                  type:
                  - boolean
                  - 'null'
                  default: false
                  description: True to require the Proof Key of Code Exchange (PKCE) flow.
                audience_uri:
                  type:
                  - string
                  - 'null'
                  description: An absolute resource URI for a confidential application (RFC 8707 section 2). Registers a resource with no accepted scopes, or adopts an unowned resource with confirmation. Every claimed URI remains permanently reserved to this app, including retirement and deletion, and counts toward the instance resource quota. Changing it stops new exchanges from the old audience immediately. Already-issued tokens retain their lifetime. Clearing requires exchange disabled in an earlier update.
                token_exchange_enabled:
                  type: boolean
                  description: Enable exchanges from the active audience. Requires an audience URI. Disabling preserves target configuration.
                adopt_audience_resource:
                  type: boolean
                  description: Confirm adoption of an existing unowned resource, preserving its accepted scopes and target references. Does not override another application's reservation.
                device_authorization_grant_enabled:
                  type:
                  - boolean
                  - 'null'
                  default: false
                  description: True to enable the OAuth Device Authorization Grant for this application. Enabling requires the new OAuth IdP and a reachable device verification page.
                public:
                  type:
                  - boolean
                  - 'null'
                  description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplicationWithSecret'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /oauth_applications/{oauth_application_id}:
    get:
      operationId: GetOAuthApplication
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: get
      summary: Retrieve an OAuth application by ID
      description: Fetches the OAuth application whose ID matches the provided `id` in the path.
      tags:
      - OAuth Applications
      parameters:
      - in: path
        name: oauth_application_id
        required: true
        schema:
          type: string
        description: The ID of the OAuth application
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplication'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateOAuthApplication
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: update
      summary: Update an OAuth application
      description: Updates an existing OAuth application
      tags:
      - OAuth Applications
      parameters:
      - in: path
        name: oauth_application_id
        required: true
        schema:
          type: string
        description: The ID of the OAuth application to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type:
                  - string
                  - 'null'
                  description: 'The new name of the OAuth application.

                    Max length: 256'
                redirect_uris:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: An array of redirect URIs of the new OAuth application
                callback_url:
                  type:
                  - string
                  - 'null'
                  maxLength: 1024
                  description: The new callback URL of the OAuth application
                  deprecated: true
                scopes:
                  type:
                  - string
                  - 'null'
                  maxLength: 1024
                  description: Replace the application's complete built-in and custom scope ceiling. Provide scope keys as a space-delimited string. Custom keys must exist in the instance OAuth scope catalog. Required built-in scopes, such as `offline_access`, must be included in the replacement set, otherwise the request is rejected. Omit this field to leave all scope assignments unchanged.
                  example: profile email offline_access public_metadata private_metadata
                consent_screen_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications.
                pkce_required:
                  type:
                  - boolean
                  - 'null'
                  description: True to require the Proof Key of Code Exchange (PKCE) flow.
                audience_uri:
                  type:
                  - string
                  - 'null'
                  description: An absolute resource URI for a confidential application (RFC 8707 section 2). Registers a resource with no accepted scopes, or adopts an unowned resource with confirmation. Every claimed URI remains permanently reserved to this app, including retirement and deletion, and counts toward the instance resource quota. Changing it stops new exchanges from the old audience immediately. Already-issued tokens retain their lifetime. Clearing requires exchange disabled in an earlier update.
                token_exchange_enabled:
                  type: boolean
                  description: Enable exchanges from the active audience. Requires an audience URI. Disabling preserves target configuration.
                adopt_audience_resource:
                  type: boolean
                  description: Confirm adoption of an existing unowned resource, preserving its accepted scopes and target references. Does not override another application's reservation.
                device_authorization_grant_enabled:
                  type:
                  - boolean
                  - 'null'
                  description: True to enable the OAuth Device Authorization Grant for this application. Enabling requires the new OAuth IdP and a reachable device verification page. Omit this field to leave the setting unchanged.
                public:
                  type:
                  - boolean
                  - 'null'
                  description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplication'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteOAuthApplication
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: delete
      summary: Delete an OAuth application
      description: 'Deletes the given OAuth application.

        This is not reversible.'
      tags:
      - OAuth Applications
      parameters:
      - in: path
        name: oauth_application_id
        required: true
        schema:
          type: string
        description: The ID of the OAuth application to delete
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /oauth_applications/{oauth_application_id}/logo:
    put:
      operationId: UploadOAuthApplicationLogo
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: uploadLogo
      summary: Upload a logo for the OAuth application
      description: 'Set or replace an OAuth application''s logo by uploading an image file.

        This endpoint uses the `multipart/form-data` request content type and accepts a file of image type.

        The file size cannot exceed 10MB.

        Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.'
      tags:
      - OAuth Applications
      parameters:
      - name: oauth_application_id
        in: path
        description: The ID of the OAuth application for which to upload a logo
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploader_user_id:
                  type: string
                  description: The ID of the user that will be credited with the image upload.
                file:
                  type: string
                  format: binary
              required:
              - file
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplication'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '413':
          $ref: '#/components/responses/ClerkErrors'
  /oauth_applications/{oauth_application_id}/rotate_secret:
    post:
      operationId: RotateOAuthApplicationSecret
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: rotateSecret
      summary: Rotate the client secret of the given OAuth application
      description: 'Rotates the OAuth application''s client secret.

        When the client secret is rotated, make sure to update it in authorized OAuth clients.'
      tags:
      - OAuth Applications
      parameters:
      - name: oauth_application_id
        in: path
        description: The ID of the OAuth application for which to rotate the client secret
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/OAuthApplicationWithSecret'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /oauth_applications/{oauth_application_id}/revoke_token:
    post:
      operationId: RevokeOAuthApplicationToken
      x-speakeasy-group: oauthApplications
      x-speakeasy-name-override: revokeToken
      summary: Revoke an OAuth application token
      description: 'Revoke both OAuth access token and refresh token for the associated grant for the given OAuth application.

        The request may specify either token.

        JWT access tokens cannot be revoked.'
      tags:
      - OAuth Applications
      parameters:
      - name: oauth_application_id
        in: path
        description: The ID of the OAuth application for which to revoke the token
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                token:
                  type: string
                  description: The opaque OAuth access token or refresh token to revoke. All tokens associated with the same OAuth grant are also revoked.
              required:
              - token
      responses:
        '204':
          description: Token revoked
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
          additionalProperties: true
        clerk_trace_id:
          type: string
      required:
      - errors
    OAuthApplicationWithSecret:
      allOf:
      - $ref: '#/components/schemas/OAuthApplication'
      - type: object
        properties:
          client_secret:
            type: string
            description: 'Empty if public client.

              '
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
        external_id:
          type: string
      required:
      - object
      - deleted
    OAuthApplications:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OAuthApplication'
        total_count:
          type: integer
          format: int64
          description: 'Total number of OAuth applications

            '
      required:
      - data
      - total_count
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
          additionalProperties: true
      required:
      - message
      - long_message
      - code
    OAuthApplication:
      type: object
      properties:
        object:
          type: string
          enum:
          - oauth_application
        id:
          type: string
        instance_id:
          type: string
        name:
          type: string
        client_id:
          type: string
        client_uri:
          type:
          - string
          - 'null'
        client_image_url:
          type:
          - string
          - 'null'
        dynamically_registered:
          type: boolean
        consent_screen_enabled:
          type: boolean
        pkce_required:
          type: boolean
        audience_uri:
          type:
          - string
          - 'null'
          description: The active application audience URI, whose registry identity is permanently reserved to this application.
        token_exchange_enabled:
          type: boolean
          description: Whether this confidential application accepts token exchanges from its active audience.
        device_authorization_grant_enabled:
          type: boolean
        public:
          type: boolean
        scopes:
          type: string
          description: 'The complete scope ceiling for the OAuth application, as a space-delimited list of built-in and assigned custom scope keys.

            '
        redirect_uris:
          type: array
          items:
            type: string
        callback_url:
          type: string
          deprecated: true
          description: 'Deprecated: Use redirect_uris instead.

            '
        authorize_url:
          type: string
        token_fetch_url:
          type: string
        user_info_url:
          type: string
        discovery_url:
          type: string
        token_introspection_url:
          type: string
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last update.

            '
      required:
      - object
      - id
      - instance_id
      - name
      - dynamically_registered
      - consent_screen_enabled
      - pkce_required
      - audience_uri
      - token_exchange_enabled
      - device_authorization_grant_enabled
      - public
      - client_id
      - client_uri
      - client_image_url
      - scopes
      - redirect_uris
      - callback_url
      - authorize_url
      - token_fetch_url
      - user_info_url
      - discovery_url
      - token_introspection_url
      - created_at
      - updated_at
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OAuthApplicationWithSecret:
      description: An OAuth application with client secret
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplicationWithSecret'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    OAuthApplications:
      description: A list of OAuth applications
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplications'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OAuthApplication:
      description: An OAuth application
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthApplication'
    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'
  parameters:
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
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