Clerk Provider

Manage the configuration of a Clerk instance through the Clerk Backend API:

• Authentication config: JWT templates, redirect URLs, sign-up allowlist and blocklist, instance settings and restrictions
• Machine-to-machine: API keys and machines
• Domains: satellite domains, plus the CNAME records for DNS as data
• Webhooks: the Svix integration
• Organizations: organizations, custom roles and permissions, verified domains, memberships
• SSO: OAuth applications and SAML connections

One provider block targets one Clerk instance. Use a provider alias for a second instance, for example dev and prod.

The provider authenticates with the instance secret key (sk_test_... or sk_live_...). It reads the key from the secret_key attribute or from the CLERK_SECRET_KEY environment variable.

This provider is pre-1.0: breaking changes can land in minor releases until v1.0.0. Pin an exact version if you need stability.

Guides

• Getting started — configure the provider and apply a first JWT template, redirect URL, and restriction.
• Dev and prod instances — one plan, two instances, provider aliases, and the DNS records.
• Adopting an existing instance — bring a configured instance under Terraform with import.
• Secrets and sensitive values — what lands in state and how to treat it.

Before you start

1. Singletons adopt, they never delete. The instance-level resources (settings, restrictions, organization settings, webhook) adopt the instance on create; destroy only removes them from state.
2. Some fields are write-only. Clerk does not return them, so the provider cannot see dashboard drift on them. Each resource doc names its write-only fields.
3. The state file holds secrets (API-key secrets, machine keys, OAuth client secrets). Treat the state as a secret; see the secrets guide.

Example Usage

terraform {
  required_providers {
    clerk = {
      source = "vanillauys/clerk"
    }
  }
}

# One provider block targets one Clerk instance.
# The secret key falls back to the CLERK_SECRET_KEY environment variable.
provider "clerk" {
  secret_key = var.clerk_secret_key_dev
}

# Use an alias for a second instance, for example production.
provider "clerk" {
  alias      = "prod"
  secret_key = var.clerk_secret_key_prod
}

resource "clerk_jwt_template" "api" {
  name     = "api"
  lifetime = 3600

  claims = jsonencode({
    role = "{{user.public_metadata.role}}"
  })
}

resource "clerk_jwt_template" "api_prod" {
  provider = clerk.prod

  name     = "api"
  lifetime = 3600

  claims = jsonencode({
    role = "{{user.public_metadata.role}}"
  })
}

Schema

Optional

• api_url (String) Base URL of the Clerk Backend API. Falls back to the CLERK_API_URL environment variable, then to https://api.clerk.com/v1.
• secret_key (String, Sensitive) Clerk secret key for the instance (sk_test_... or sk_live_...). Falls back to the CLERK_SECRET_KEY environment variable.