# Clerk Provider

Manage the configuration of a [Clerk](https://clerk.com) instance through the
[Clerk Backend API](https://clerk.com/docs/reference/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](/docs/clerk/guides/getting-started) — configure the provider and
  apply a first JWT template, redirect URL, and restriction.
- [Dev and prod instances](/docs/clerk/guides/dev-and-prod-instances) — one plan, two
  instances, provider aliases, and the DNS records.
- [Adopting an existing instance](/docs/clerk/guides/adopting-an-existing-instance) —
  bring a configured instance under Terraform with import.
- [Secrets and sensitive values](/docs/clerk/guides/secrets) — 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](/docs/clerk/guides/secrets).

## Example Usage

```terraform
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 generated by tfplugindocs -->
## 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.