Clerk docs

OAuth Applications

OAuth applications contain data for clients using Clerk as an OAuth2 identity provider.

Get a list of OAuth applications for an instance

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.

SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

Responses
200

A list of OAuth applications

400

Request was not successful

403

Authorization invalid

422

Invalid request parameters

get/oauth_applications
Response samples
application/json
{
  • "data": [
    ],
  • "total_count": 0
}

Create an OAuth application

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

SecuritybearerAuth
Request
Request Body schema: application/json
name
required
string

The name of the new OAuth application

callback_url
required
string

The callback URL of the new OAuth application

scopes
string
Default: "profile email"

Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are profile, email, public_metadata, private_metadata. Provide the requested scopes as a string, separated by spaces.

public
boolean

If true, this client is public and cannot securely store a client secret. Only the authorization code flow with proof key for code exchange (PKCE) may be used. Public clients cannot be updated to be confidential clients, and vice versa.

Responses
200

An OAuth application with client secret

400

Request was not successful

403

Authorization invalid

422

Invalid request parameters

post/oauth_applications
Request samples
application/json
{
  • "name": "string",
  • "callback_url": "string",
  • "scopes": "profile email public_metadata",
  • "public": true
}
Response samples
application/json
{
  • "object": "oauth_application",
  • "id": "string",
  • "instance_id": "string",
  • "name": "string",
  • "client_id": "string",
  • "public": true,
  • "scopes": "string",
  • "callback_url": "string",
  • "authorize_url": "string",
  • "token_fetch_url": "string",
  • "user_info_url": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "client_secret": "string"
}

Retrieve an OAuth application by ID

Fetches the OAuth application whose ID matches the provided id in the path.

SecuritybearerAuth
Request
path Parameters
oauth_application_id
required
string

The ID of the OAuth application

Responses
200

An OAuth application

403

Authorization invalid

404

Resource not found

get/oauth_applications/{oauth_application_id}
Response samples
application/json
{
  • "object": "oauth_application",
  • "id": "string",
  • "instance_id": "string",
  • "name": "string",
  • "client_id": "string",
  • "public": true,
  • "scopes": "string",
  • "callback_url": "string",
  • "authorize_url": "string",
  • "token_fetch_url": "string",
  • "user_info_url": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Update an OAuth application

Updates an existing OAuth application

SecuritybearerAuth
Request
path Parameters
oauth_application_id
required
string

The ID of the OAuth application to update

Request Body schema: application/json
required
name
string

The new name of the OAuth application

callback_url
string

The new callback URL of the OAuth application

scopes
string
Default: "profile email"

Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are profile, email, public_metadata, private_metadata. Provide the requested scopes as a string, separated by spaces.

Responses
200

An OAuth application

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

patch/oauth_applications/{oauth_application_id}
Request samples
application/json
{
  • "name": "string",
  • "callback_url": "string",
  • "scopes": "profile email public_metadata private_metadata"
}
Response samples
application/json
{
  • "object": "oauth_application",
  • "id": "string",
  • "instance_id": "string",
  • "name": "string",
  • "client_id": "string",
  • "public": true,
  • "scopes": "string",
  • "callback_url": "string",
  • "authorize_url": "string",
  • "token_fetch_url": "string",
  • "user_info_url": "string",
  • "created_at": 0,
  • "updated_at": 0
}

Delete an OAuth application

Deletes the given OAuth application. This is not reversible.

SecuritybearerAuth
Request
path Parameters
oauth_application_id
required
string

The ID of the OAuth application to delete

Responses
200

Deleted Object

403

Authorization invalid

404

Resource not found

delete/oauth_applications/{oauth_application_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}

Rotate the client secret of the given OAuth application

Rotates the OAuth application's client secret. When the client secret is rotated, make sure to update it in authorized OAuth clients.

SecuritybearerAuth
Request
path Parameters
oauth_application_id
required
string

The ID of the OAuth application for which to rotate the client secret

Responses
200

An OAuth application with client secret

403

Authorization invalid

404

Resource not found

post/oauth_applications/{oauth_application_id}/rotate_secret
Response samples
application/json
{
  • "object": "oauth_application",
  • "id": "string",
  • "instance_id": "string",
  • "name": "string",
  • "client_id": "string",
  • "public": true,
  • "scopes": "string",
  • "callback_url": "string",
  • "authorize_url": "string",
  • "token_fetch_url": "string",
  • "user_info_url": "string",
  • "created_at": 0,
  • "updated_at": 0,
  • "client_secret": "string"
}
➔ Next to Organizations