Use Clerk as an OAuth 2.0 provider

Clerk can be configured as an OAuth 2.0 provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. This feature allows users to authenticate to other applications using their Clerk credentials, enabling user information sharing between your Clerk application and OAuth clients.

When should you use Clerk as an OAuth 2.0 provider?

You can use Clerk as an OAuth 2.0 provider if you want your users to authenticate to a third party site or a tool using their credentials from your application. This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see the dedicated guide.

How it works

Clerk is the OAuth 2.0 provider for your application. The "client" is the third party site or tool that you want your users to authenticate to.

In order to make your Clerk instance operate as an OAuth 2.0 provider, create an OAuth application in the Clerk Dashboard. Then, configure the client to work with your Clerk instance, using the necessary data from your Clerk OAuth application.

Create a Clerk OAuth application

To create an OAuth application,

1. In the Clerk Dashboard, navigate to the OAuth Applications⁠ page.
2. Select the Add OAuth application button. A modal will open.
3. Complete the following fields:
   • Name - Helps you to identify your application.
   • Scopes - The scopes that you would like to leverage.
4. Select the Create button. You'll be redirected to your app's settings page.
5. In the Redirect URI field, add the redirect URI that the client provides. This is the URL that Clerk will redirect to after the user has authenticated.

Configure your client

Now that you have set up a Clerk OAuth application, you will need to configure any of the following settings needed in your client.

• Client ID: Public identifier of your Clerk OAuth application.
• Client Secret: Confidential secret used to authenticate your Clerk OAuth application.
• Authorize URL: Used by the client to request authorization from your user.
• Token URL: Used by the client to exchange an authorization code for an access token and a refresh token.
• User Info URL: Used by the client to retrieve additional user data upon authentication.
• Discovery URL: Used by the client to retrieve the configuration data of the Clerk OAuth application.

OAuth 2.0 Scopes

OAuth 2.0 scopes define the level of access and specific user data that will be shared with the client application during authentication. The following scopes are currently supported:

Get user information

After a user has successfully completed an OAuth 2.0 flow, you can retrieve additional user information from Clerk's /oauth/userinfo⁠ endpoint, based on the granted scopes. When making the request to this endpoint, you must include the Clerk access token in the Authorization header.

The /oauth/userinfo endpoint provides the following user properties, depending on the granted scopes:

Get token information

For validating access tokens or refresh tokens and retrieving additional token metadata, Clerk provides a standard OAuth 2.0 Token Introspection Endpoint⁠ at /oauth/token_info⁠.

The endpoint returns detailed token information such as if the token is still active, the client ID, and the granted scopes.

OAuth 2.0 grant types

Clerk OAuth 2.0 provider supports the following flows and grant types:

• Authorization Code⁠
• PKCE⁠
• Refresh token⁠

Frequently asked questions (FAQ)

When do the tokens expire?

Authorization codes expire after 10 minutes. Access tokens expire after 2 hours. Refresh tokens expire after 3 days.

Is OpenID Connect (OIDC) supported?

At this time, OIDC is not supported.