Fauna

Learn how to integrate Clerk into your 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.

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
import { useAuth } from '@clerk/nextjs';
2
import faunadb from 'faunadb';
3
const q = faunadb.query;
4

5
const Example = () => {
6
  const { getToken } = useAuth();
7
  const [userId, setUserId] = React.useState();
8
  const makeQuery = async () => {
9
    try {
10
      // TODO: Update with your JWT template name
11
      const secret = await getToken({ template: 'fauna' });
12
      const client = new faunadb.Client({ secret, keepAlive: false });
13
      const id = await client.query(q.CurrentIdentity());
14
      setUserId(id);
15
    } catch (e) {
16
      // Handle error
17
      setUserId(null);
18
    }
19
  };
20

21
  return (
22
    <>
23
      <button onClick={makeQuery}>Make authenticated query</button>
24
      <p>User ID: {userId}</p>
25
    </>
26
  );
27
};

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

Replace the Fauna JavaScript driver with a GraphQL client like Apollo or graphql-request
Try adding some custom claims to the JWT token
Get support or at least say hi in our Discord channel