Skip to main content
Docs
Dashboard

Use OAuth for scoped access

Clerk's OAuth implementation supports OAuth Scoped Access, which lets third-party applications request limited access to specific parts of a user's data through Clerk's API. This enables applications to interact with user data in a secure and controlled manner, based on the user’s explicit consent. The most common implementation of OAuth Scoped Access is the "Authorization Code Flow", which is the flow covered in this guide.

How the flow works

Before diving into implementations details, it's important to understand the different actors involved in this flow:

  • Client - The third-party app that wants to access a user's data from your application (resource service). This app is configured to obtain OAuth tokens from Clerk.
  • Authorization service - The service that authorizes the user and grants the OAuth tokens. In this example, Clerk would be the authorization service.
  • Resource service - The backend server that hosts the user's data that the client wants to access. In this example, this would be your own application that uses Clerk for authentication and route protection.

Note

If you would like to know more about the terminology around OAuth, check out the OAuth terminology guide.

This guide provides step-by-step instructions on how to build OAuth scoped access into a Clerk app.

Before you start

Let's begin by creating an OAuth application in the Clerk Dashboard.

Create a Clerk OAuth application

  1. In the Clerk Dashboard, navigate to the OAuth Applications page.

  2. Select Add OAuth application. A modal will open.

  3. Complete the following fields:

    • Name - Helps you identify your application.

    • Scopes - The scopes that you would like to leverage. To find out more about the scopes currently supported by Clerk, check out the OAuth reference documentation.

      A screenshot of a new OAuth application being created in the Clerk dashboard

  4. Select Add. A modal will open with your Client Secret. Ensure that you copy this and store it somewhere secure.

    Warning

    For security reasons, Clerk does not store your Client Secret and cannot show it to you again, so ensure that you copy it and store it somewhere secure, like an environment variable.

  5. You'll be redirected to your OAuth app's settings page. Under Application credentials, you can find your Client ID, which will be necessary to complete the OAuth flow.

  6. In the Redirect URIs field, add the redirect URI provided by your client. This is the URL that Clerk will redirect to with an authorization code after the user has authenticated and consented to the access request. For this example, we will use http://localhost:3000/oauth_callback.

    A screenshot of the redirect urls, client id, and client secret within an OAuth application in the Clerk dashboard

The Clerk setup is now complete. If you'd like to know more about other OAuth application configuration settings, refer to the dedicated reference documentation.

Test the OAuth flow

If you are aiming to integrate your Clerk app with a third-party app that acts as an OAuth client, you can reference their documentation on how to integrate OAuth connections in order to test your OAuth flow. It will likely be necessary to provide the client_id, client_secret, and redirect_uri from the OAuth app created above.

If you don't have a specific, existing OAuth client in mind, you can use the following OAuth test client project. It contains a minimal Express.js server that can run through an OAuth flow. Let's walk through how to use this test client below.

Note

This implementation follows the OAuth specification, and is not specific to Clerk or this test project. Any compliant OAuth client will behave the same way.

  1. Clone the following repository to your machine.

  2. In your terminal and within your project, run the following command:

    terminal
    cp .env.sample .env

  3. In your newly created .env file, add the required credentials:

    • CLERK_PUBLISHABLE_KEY: Your Clerk Publishable Key from the API keys page in the Clerk Dashboard.
    • CLIENT_ID: The client ID of your OAuth app from the Clerk Dashboard.
    • CLIENT_SECRET: The client secret of your OAuth app from the Clerk Dashboard.

  4. In your terminal, run the following command to install dependencies:

    terminal
    npm i

  5. In your terminal, run the following command to start the server:

    terminal
    npm start

Finished 🎉

Once this is complete, you'll be able to see the OAuth flow begin. If you are not currently signed in, you'll first be presented with a sign in screen. After signing in, Clerk will redirect to an OAuth consent screen, showing the requested scopes and asking for your consent.

Note

The consent screen uses the scopes passed in the authorization request to inform the user exactly what they’re granting access to, and to whom.

By default, the consent screen is shown for all newly created OAuth apps, but this can be toggled in each app’s settings on the Clerk Dashboard, although not recommended.

For more details on how Clerk's OAuth consent screen works, see the OAuth consent screen reference docs.

Once you have accepted, you'll be redirected to the OAuth callback route, the redirect_uri specified earlier. This process will exchange the authorization code for an access token, and render the access token and refresh token as a JSON response, similar to this:

{
  "access_token": "xxx",
  "expires_in": 7200,
  "id_token": "xxx",
  "refresh_token": "xxx",
  "scope": "openid email profile",
  "token_type": "bearer"
}

With the OAuth flow complete, the client now has a working access token. The next step would normally be for the client to use that token to make an authenticated request to your app's API endpoints. To learn more about how to accept and verify OAuth tokens using Clerk, see the guide on verifying OAuth tokens.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on