OAuth Applications

Create an OAuth application

Changed on

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...

post/oauth_applications

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/oauth_applications
  • Auth: HTTP bearer

Request body

namestring required

The name of the new OAuth application. Max length: 256

redirect_urisstring[] nullable

An array of redirect URIs of the new OAuth application

callback_urlstring nullable

The callback URL of the new OAuth application

scopesstring nullable

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.

consent_screen_enabledboolean nullable

True to enable a consent screen to display in the authentication flow.

pkce_requiredboolean nullable

True to require the Proof Key of Code Exchange (PKCE) flow.

audience_uristring nullable

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_enabledboolean

Enable exchanges from the active audience. Requires an audience URI. Disabling preserves target configuration.

adopt_audience_resourceboolean

Confirm adoption of an existing unowned resource, preserving its accepted scopes and target references. Does not override another application's reservation.

device_authorization_grant_enabledboolean nullable

True to enable the OAuth Device Authorization Grant for this application. Enabling requires the new OAuth IdP and a reachable device verification page.

publicboolean nullable

If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.

Example request

{
  "scopes": "profile email public_metadata"
}

Response

An OAuth application with client secret

object'oauth_application' required
idstring required
instance_idstring required
namestring required
client_idstring required
client_uristring nullable required
client_image_urlstring nullable required
dynamically_registeredboolean required
consent_screen_enabledboolean required
pkce_requiredboolean required
audience_uristring nullable required

The active application audience URI, whose registry identity is permanently reserved to this application.

token_exchange_enabledboolean required

Whether this confidential application accepts token exchanges from its active audience.

device_authorization_grant_enabledboolean required
publicboolean required
scopesstring required

The complete scope ceiling for the OAuth application, as a space-delimited list of built-in and assigned custom scope keys.

redirect_urisstring[] required
callback_urlstring required

Deprecated: Use redirect_uris instead.

authorize_urlstring required
token_fetch_urlstring required
user_info_urlstring required
discovery_urlstring required
token_introspection_urlstring required
created_atinteger required

Unix timestamp of creation.

updated_atinteger required

Unix timestamp of last update.

client_secretstring

Empty if public client.

Changes

  • 2025-11-107db12d6a9b2aRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

  • 2025-11-10b5f30169c3f3Revision changes
    • info

      added the new optional request property

    • info

      added the required property //// to the response with the status