Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

Fauna

Learn how to integrate Clerk into your Next.js + Fauna application

Getting started

The first step is to create a new Clerk application from your Clerk Dashboard if you haven’t done so already. You can choose whichever authentication strategy and social login providers you prefer. For more information, check out our Set up your application guide.

After your Clerk application has been created, navigate to the API keys page and copy your Frontend API key.

The next step is to head over to the Fauna database that you want Clerk-authenticated users to access. Click on the Security link on the left-hand navigation and then the Providers tab.

Click the New Access Provider button.

Enter a name in the Name field that will identify this access provider. The recommendation is to use “Clerk”.

Paste the Frontend API key you copied from the Clerk Dashboard into the Issuer field and then prefix it with the https:// protocol so it follows https://<YOUR_FRONTEND_API>

Note: Make sure you do not add a trailing slash / to the end of the Issuer URL or it will fail.

Assuming you didn’t use a custom signing key, set the JWKS endpoint field to the JSON Web Key Set (JWKS) URL Clerk automatically created with your Frontend API at https://<YOUR_FRONTEND_API>/.well-known/jwks.json

The last part is to select a role that will be assigned to authenticated users. The Role defines the access privileges and domain-specific security rules. You can specify multiple roles if necessary.

The completed provider form should resemble the following:

Before clicking the Save button, copy the Audience URL then go ahead and save.

JWT Template

Navigate back to the Clerk Dashboard and click on the JWT Templates configuration section.

Click on the button to create a new Fauna template.

Give your JWT template a short, but meaningful name (e.g. fauna).

Add in the aud claim set to the Audience URL you copied from Fauna. The URL format should be https://db.fauna.com/db/<YOUR_FAUNA_DB_ID>

You can include additional claims if you’d like, but aud is the only required one. Shortcodes are available to make adding dynamic user values easy.

Click the “Apply changes” button and your Fauna JWT template will be saved.

Client connection

To validate the token authentication with Fauna, you will need to have a client application that has a Clerk JavaScript library installed.

Clerk has an official clerk-fauna-starter repo built with Next.js that you can use. If you already have an application with the Clerk library installed, you can skip ahead to the section called 'Authenticating Fauna queries.'

Clone the starter repo from GitHub to your local machine, change into the project directory, and install the package dependencies with the following commands:

A sample environment variable config file is available. Copy this file to .env.local with:

Set CLERK_API_KEY to your Clerk Backend API key and NEXT_PUBLIC_CLERK_FRONTEND_API to your Frontend API key. Both are available on the Clerk Dashboard or in the API Keys section.

After setting those environment variables, spin up the Next.js development server:

Browse to http://localhost:3000 and you should see the following screen:

If you haven’t already signed up for an account in the application do so now. Once you have signed in, you will be presented with the following:

Click the first button to query Fauna. If the JWT authentication has been successful, you will see a user ID in the response output:

If all went well, you can now make authenticated queries to your Fauna database.

If the current user ID is not returned, check the browser console for errors and reach out for support if needed.

Authenticating Fauna queries

The way to authenticate requests to Fauna with Clerk is to use a JWT. After adding the necessary claims in a JWT template, you can generate the token by calling the getToken method from the useSession hook provided by Clerk:

1

Note: The getToken({ template: <your-template-name> }) call is asynchronous and returns a Promise that needs to be resolved before accessing the token value. This token is short-lived for better security and should be called before every request to your Fauna database. The caching and refreshing of the token are handled automatically by Clerk.

Next Steps


Was this helpful?

Clerk © 2022