Skip to main content

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

TestPasses when
Active Clerk users have MFA, a passkey or SSOevery user who is not banned has a second factor, a passkey or an enterprise SSO account
Clerk organisation admins have MFA, a passkey or SSOthe same, for every user with the org:admin role
No Clerk users have been inactive for more than a yearevery 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
Every Clerk organisation has an adminClerk reports no organisation without a member who can manage it
No banned Clerk users hold an organisation admin roleno banned or deprovisioned user holds org:admin
Clerk SAML IdP certificates do not expire within 30 daysevery active SAML connection has a certificate valid for more than 30 days

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 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.