# Clerk

> Connect your Clerk instance to Tidal Control with a secret key, so compliance tests check MFA, inactive users, organisation admins and SAML certificates.

Source: https://tidalcontrol.com/docs/integrations/clerk

Tidal Control's Clerk integration reads the authentication posture of one Clerk instance for compliance purposes. It authenticates with a secret key against the Clerk Backend API (`https://api.clerk.com/v1`) and only sends read requests.

Clerk is usually the sign-in layer inside your own product, so the users this integration reads are the end users of your application, not your staff. Their MFA adoption, inactive accounts and admin roles are what an auditor asks about when your product holds customer data.

## What this integration monitors

- **Users:** Second factors, passkeys, enterprise SSO accounts, banned and locked accounts, and last activity
- **Organisations:** Whether every organisation has an admin, who holds the admin role, and banned users who still hold it
- **Enterprise SSO:** Active SAML and OIDC connections, and when each SAML identity provider certificate expires

## Tests

<table>
<thead>
<tr><th>Test</th><th>Passes when</th></tr>
</thead>
<tbody>
<tr><td>Active Clerk users have MFA, a passkey or SSO</td><td>every user who is not banned has a second factor, a passkey or an enterprise SSO account</td></tr>
<tr><td>Clerk organisation admins have MFA, a passkey or SSO</td><td>the same, for every user with the <code>org:admin</code> role</td></tr>
<tr><td>No Clerk users have been inactive for more than a year</td><td>every user who is not banned was active in the last year; a user who never signed in is judged by when the account was created</td></tr>
<tr><td>Every Clerk organisation has an admin</td><td>Clerk reports no organisation without a member who can manage it</td></tr>
<tr><td>No banned Clerk users hold an organisation admin role</td><td>no banned or deprovisioned user holds <code>org:admin</code></td></tr>
<tr><td>Clerk SAML IdP certificates do not expire within 30 days</td><td>every active SAML connection has a certificate valid for more than 30 days</td></tr>
</tbody>
</table>

Users who sign in through enterprise SSO pass the MFA tests, because their identity provider enforces MFA rather than Clerk.

## Requirements

- Super User role in Tidal Control
- Access to the **API keys** page of your Clerk production instance

> **warning:**

**A Clerk secret key cannot be limited to read access.** Every secret key can read and change everything in its instance, including deleting users. Tidal Control only sends read requests, but create a dedicated key for it, so you can revoke that key without touching the keys your application uses.

## Configuration step-by-step plan

We'll create a dedicated secret key in Clerk, then add the connection in Tidal Control.

**Configuration steps:**

1. **Create a secret key**
2. **Configure the integration in Tidal Control**

## Step 1: Create a secret key

- Log in to the [Clerk Dashboard](https://dashboard.clerk.com) and open your application
- Switch to your **production** instance. A development instance holds test data, and its results would not describe your product
- Open **API keys** and add a new secret key named `Tidal Control`
- Copy the key. It starts with `sk_live_`

The publishable key on the same page starts with `pk_` and is meant for your frontend. It cannot reach the Backend API and will not work here.

## Step 2: Configure the integration in Tidal Control

- Go to **Settings → Integrations** in Tidal Control
- Click the **plus icon** next to **Clerk**
- Fill in the configuration:
  - **Name:** A descriptive name, for example `Clerk`
  - **Secret key:** The key from step 1, without quotes or surrounding spaces
- Click **"Create"** to save the integration

## Configuration fields explained

**Name:**
- A descriptive name for this connection
- For example: `Clerk`, `Clerk production`

**Secret key:**
- A Clerk secret key starting with `sk_live_`
- Required, and stored as a secret
- A development key starting with `sk_test_` is accepted for trying the integration out

## Verification

The integration is working when all of the following are true:

- Settings → Integrations shows Clerk under **Configured Integrations**
- Clerk tests are available in the Tests section
- Test refresh delivers results without authentication errors

## Frequently asked questions

**Which users does Tidal Control read?**
The users of the Clerk instance the key belongs to, which are normally the end users of your application. Clerk Dashboard members, the people who administer Clerk itself, are not available through the Backend API.

**Can Tidal Control check whether MFA is required for everyone?**
No. Clerk's Backend API does not expose instance settings such as required MFA, the password policy or session lifetime. The tests read each user's actual state instead.

**Why do the organisation tests show no results?**
Organisations are a Clerk feature you switch on per instance. When it is off, there are no organisations or admin roles to check, and those tests pass with no results.

**Why does the SAML certificate test show no results?**
Enterprise SSO needs a paid Clerk plan, and OIDC connections have no certificate. Without an active SAML connection there is nothing to check.

## Common problems

**Tests error with an authentication failure**
- Confirm that you copied a secret key starting with `sk_live_`, not the publishable key starting with `pk_`
- If the key was revoked in the Clerk Dashboard, create a new one and update the connection before refreshing the tests

**Results describe test users**
- The connection uses a development key (`sk_test_`). Edit the connection and paste a key from your production instance

### Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

> **info:**

**Gather support info:** Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.
