Clerk

​

At a glance

npx @deploybaseline/cli start --service clerk

import { createEmulator } from "@deploybaseline/cli";

const clerk = await createEmulator({ service: "clerk" });
// clerk.url is http://localhost:4000

{
  "clerk": {
    "users": [
      {
        "first_name": "Test",
        "last_name": "User",
        "email_addresses": ["[email protected]"],
        "password": "clerk_test_password"
      }
    ],
    "organizations": [
      {
        "name": "My Company",
        "slug": "my-company",
        "members": [
          {
            "email": "[email protected]",
            "role": "admin"
          }
        ]
      }
    ],
    "oauth_applications": [
      {
        "client_id": "clerk_baseline_client",
        "client_secret": "clerk_baseline_secret",
        "name": "Baseline App",
        "redirect_uris": ["http://localhost:3000/api/auth/callback/clerk"]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service clerk

import { createEmulator } from '@deploybaseline/cli'

const clerk = await createEmulator({ service: 'clerk', port: 4010 })
// clerk.url === 'http://localhost:4010'

​

@clerk/backend

import { createClerkClient } from '@clerk/backend'

const clerk = createClerkClient({
  secretKey: 'sk_test_baseline',
  apiUrl: process.env.CLERK_EMULATOR_URL, // e.g. http://localhost:4010
})

const { data: users } = await clerk.users.getUserList()

​

@clerk/nextjs, @clerk/clerk-react, and clerk-js

# .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_YmFzZWxpbmUuY2xlcmsuYWNjb3VudHMuZGV2JA
NEXT_PUBLIC_CLERK_PROXY_URL=http://localhost:4010
CLERK_SECRET_KEY=sk_test_baseline
CLERK_API_URL=http://localhost:4010

import { Clerk } from '@clerk/clerk-js'

const clerk = new Clerk(publishableKey, { proxyUrl: 'http://localhost:4010' })
await clerk.load()
const signIn = await clerk.client.signIn.create({ identifier: '[email protected]', password: 'test_password' })
await clerk.setActive({ session: signIn.createdSessionId })

​

OIDC clients

// Auth.js generic OIDC provider
{
  id: 'clerk',
  name: 'Clerk',
  type: 'oidc',
  issuer: process.env.CLERK_EMULATOR_URL,
  clientId: 'clerk_baseline_client',
  clientSecret: 'clerk_baseline_secret',
}

​

Auth

​

Frontend API

{
  "frontend_api": "baseline.clerk.accounts.dev",
  "proxy_url": "http://localhost:4010",
  "publishable_key": "pk_test_YmFzZWxpbmUuY2xlcmsuYWNjb3VudHMuZGV2JA",
  "publishable_key_live": "pk_live_YmFzZWxpbmUuY2xlcmsuYWNjb3VudHMuZGV2JA"
}

• POST /v1/dev_browser — Create dev browser token (Clerk-Db-Jwt header). Development instances carry the client in __clerk_db_jwt; an unknown token is 401 dev_browser_unauthenticated.
• GET and PATCH /v1/environment: auth, display, user, and organization settings from clerk.instance.
• GET, PUT, POST, and DELETE /v1/client; DELETE /v1/client/sessions.
• GET /v1/client/sessions/:id, POST .../touch (active_organization_id sets the active organization), .../end, .../remove, .../tokens (organization_id picks the organization, "" the personal account), and .../tokens/:template.
• Sign-ins: POST /v1/client/sign_ins (identifier and password, email_code, reset_password_email_code, oauth_*, transfer), GET .../:id, .../prepare_first_factor, .../attempt_first_factor, .../reset_password.
• Sign-ups: POST /v1/client/sign_ups, GET and PATCH .../:id, .../prepare_verification, .../attempt_verification (email codes).
• /v1/me: GET, PATCH, DELETE, PATCH /v1/me/metadata, POST /v1/me/change_password, email addresses (add, read, verify, delete), GET /v1/me/organization_memberships, and DELETE /v1/me/organization_memberships/:organizationId.
• GET /v1/client/handshake and the Backend API’s GET /v1/clients/handshake_payload, so authenticateRequest can refresh a missing or expired __session cookie.
• Social sign-in: an oauth_* strategy returns an external_verification_redirect_url to the emulator’s account chooser at /_clerk/oauth/:strategy, which returns through /v1/oauth_callback to the attempt’s redirect_url. A new account on sign-in (or a taken one on sign-up) becomes transferable, as on Clerk.

• Session tokens (60 seconds) are v2: sid, sub, azp (the request’s origin), iss (https://<frontend_api>), nbf, exp, iat, v: 2, fva, and with an active organization o: { id, rol, slg, per, fpm }. verifyToken and authenticateRequest from @clerk/backend accept them against the emulator’s JWKS.
• Passwords are checked for length (form_password_length_too_short, minimum password_min_length) and against a list of breached passwords (form_password_pwned, off with hibp: false). A taken email or username is form_identifier_exists, an unknown one at sign-in form_identifier_not_found, and a wrong password form_password_incorrect.
• Codes are not emailed. GET /_clerk/emails?email_address= lists the codes sent, GET /_clerk/simulate/verification-code?email_address= returns the latest, and the inspector’s Emails tab shows them. Addresses with +clerk_test take 424242 and get no code, while test_mode is on (the default on development instances).
• Single session mode is on by default: a second sign-in on a signed-in client is session_exists. Seed single_session_mode: false for multi-session apps.
• Sessions made here are Backend API sessions: GET /v1/sessions lists them, and revoking one through the Backend API signs the browser out.
• GET /npm/* redirects clerk-js and @clerk/ui bundle requests to the public npm CDN, so the SDK’s script loader works through proxyUrl. Offline, serve the bundle yourself (clerkJSUrl).

​

OAuth and OIDC

• GET /.well-known/openid-configuration — OIDC discovery
• GET /v1/jwks — JSON Web Key Set (JWKS)
• GET /oauth/authorize — Authorize: shows the user picker
• POST /oauth/authorize/callback — Submit user picker: redirects to redirect_uri with code and state
• POST /oauth/token — Exchange token (authorization_code and refresh_token grants)
• GET /oauth/userinfo — Get user info: for an OAuth access token
• POST /oauth/token_info — Introspect token (RFC 7662): for the client the token was issued to
• POST /oauth/token/revoke — Revoke token (RFC 7009); revoking a refresh token also ends the access tokens of its grant
• GET /oauth/authorize/deny — Deny consent: the consent screen’s Deny link, redirects with error=access_denied

​

Authorization code flow

1. Redirect the user to /oauth/authorize with client_id, redirect_uri, scope, state, and optionally nonce, code_challenge, and code_challenge_method
2. The emulator renders a user picker with every seeded user
3. On selection, the emulator redirects to redirect_uri with code and state
4. Exchange the code via POST /oauth/token with grant_type=authorization_code

​

Consent screen

​

Signing key

​

Users

• GET /v1/users — List users (limit, offset, query, email_address, external_id, username, user_id, order_by). Filters other than query may repeat.
• GET /v1/users/count — Count users (same filters)
• GET /v1/users/:userId — Get user
• POST /v1/users — Create user (422 form_identifier_exists for an email address or username already in use, 422 form_param_format_invalid for a malformed email)
• PATCH /v1/users/:userId — Update user
• DELETE /v1/users/:userId — Delete user and its email addresses, memberships, and sessions
• POST /v1/users/:userId/ban — Ban user
• POST /v1/users/:userId/unban — Unban user
• POST /v1/users/:userId/lock — Lock user
• POST /v1/users/:userId/unlock — Unlock user
• PATCH /v1/users/:userId/metadata — Merge user metadata: deep merge public, private, and unsafe metadata (null removes a key)
• PUT /v1/users/:userId/metadata — Replace user metadata: replaces each metadata field sent; fields left out are kept
• GET /v1/users/:userId/organization_memberships — List user memberships (limit, offset, role, order_by)
• POST /v1/users/:userId/verify_password — Verify password ({ "verified": true }, or 422 form_password_incorrect)

​

Email addresses

• GET /v1/email_addresses/:emailId — Get email address
• POST /v1/email_addresses — Create email address
• PATCH /v1/email_addresses/:emailId — Update email address
• DELETE /v1/email_addresses/:emailId — Delete email address

​

Organizations

• GET /v1/organizations — List organizations (limit, offset, query)
• GET /v1/organizations/:orgId — Get organization by ID or slug
• POST /v1/organizations — Create organization (created_by adds that user as org:admin; a slug already in use, ignoring case, is 422 form_identifier_exists)
• PATCH /v1/organizations/:orgId — Update organization (the same slug check)
• DELETE /v1/organizations/:orgId — Delete organization
• PATCH /v1/organizations/:orgId/metadata — Merge organization metadata: deep merge (null removes a key)
• PUT /v1/organizations/:orgId/metadata — Replace organization metadata: replaces each metadata field sent

​

Memberships

• GET /v1/organization_memberships — List all memberships: across every organization (limit, offset, user_id, role, order_by; filters may repeat)
• GET /v1/organizations/:orgId/memberships — List members (limit, offset, role)
• POST /v1/organizations/:orgId/memberships — Add member
• PATCH /v1/organizations/:orgId/memberships/:userId — Update member role
• DELETE /v1/organizations/:orgId/memberships/:userId — Remove member (returns the removed membership)
• PATCH /v1/organizations/:orgId/memberships/:userId/metadata — Merge membership metadata: deep merge

​

Invitations

• GET /v1/organizations/:orgId/invitations — List invitations (limit, offset, status, which may repeat)
• GET /v1/organizations/:orgId/invitations/:invitationId — Get invitation
• POST /v1/organizations/:orgId/invitations — Create invitation (email_address, role, inviter_user_id, public_metadata, private_metadata, expires_in_days from 1 to 365)
• POST /v1/organizations/:orgId/invitations/bulk — Create invitations in bulk: from an array of invitation bodies; returns { data, total_count }
• POST /v1/organizations/:orgId/invitations/:invitationId/revoke — Revoke invitation: a pending one

​

Sessions

• GET /v1/sessions — List sessions (limit, offset, user_id, status such as active or revoked)
• GET /v1/sessions/:sessionId — Get session
• POST /v1/sessions — Create session: for a user_id
• POST /v1/sessions/:sessionId/revoke — Revoke session
• POST /v1/sessions/:sessionId/tokens — Create session token (JWT)
• POST /v1/sessions/:sessionId/tokens/:template — Create session token from template (404 when no template has that name)

​

Session tokens

{
  "clerk": {
    "jwt_templates": [
      {
        "name": "supabase",
        "lifetime": 3600,
        "claims": {
          "aud": "authenticated",
          "role": "authenticated",
          "email": "{{user.primary_email_address}}"
        },
        "custom_signing_key": true,
        "signing_algorithm": "HS256",
        "signing_key": "super-secret-jwt-token-with-at-least-32-characters"
      }
    ]
  }
}

​

JWT templates

• GET /v1/jwt_templates — List templates (a plain array, or { data, total_count } with paginated=true)
• GET /v1/jwt_templates/:templateId — Get template
• POST /v1/jwt_templates — Create template (name, claims, lifetime, allowed_clock_skew, custom_signing_key, signing_algorithm, signing_key)
• PATCH /v1/jwt_templates/:templateId — Update template
• DELETE /v1/jwt_templates/:templateId — Delete template

​

Instance

• GET /v1/instance — Get instance (clerk.instance.get()): id, environment_type, allowed_origins, and the subdomain settings
• PATCH /v1/instance — Update instance: settings such as allowed_origins (an empty list clears it; null leaves a setting unchanged), support_email, test_mode, hibp; 204

​

Seed config

{
  "clerk": {
    "instance": {
      "allowed_origins": ["chrome-extension://abcdef"],
      "application_name": "My App",
      "single_session_mode": true,
      "attributes": {
        "username": "required",
        "first_name": "on",
        "last_name": "on",
        "password": "required"
      },
      "password_min_length": 8,
      "social_providers": ["oauth_google", "oauth_github"]
    },
    "users": [
      {
        "first_name": "Jane",
        "last_name": "Doe",
        "username": "jane",
        "email_addresses": ["[email protected]"],
        "password": "jane_password",
        "public_metadata": {
          "plan": "pro"
        }
      }
    ],
    "organizations": [
      {
        "name": "My Company",
        "slug": "my-company",
        "max_allowed_memberships": 10,
        "members": [
          {
            "email": "[email protected]",
            "role": "admin"
          }
        ]
      }
    ],
    "oauth_applications": [
      {
        "client_id": "clerk_baseline_client",
        "client_secret": "clerk_baseline_secret",
        "name": "Baseline App",
        "redirect_uris": ["http://localhost:3000/api/auth/callback/clerk"],
        "scopes": ["openid", "profile", "email"]
      }
    ]
  }
}

• users: email_addresses (required, the first is primary and all are verified), clerk_id, first_name, last_name, username, password, external_id, public_metadata, private_metadata, unsafe_metadata. A user whose first email already exists (such as the default [email protected]) is updated with the fields the entry sets, and keeps its ID.
• organizations: name (required), clerk_id, slug (derived from name when omitted), max_allowed_memberships, public_metadata, private_metadata, members. Each member references a seeded user by email; role gets an org: prefix when missing.
• instance: id (defaults to ins_baseline00000000000000000) and allowed_origins for GET /v1/instance, and the Frontend API settings: frontend_api (the host the publishable keys encode, default baseline.clerk.accounts.dev), environment_type (development or production), application_name, single_session_mode (default true), attributes (username, first_name, last_name, password as on, off, or required; email is always required), password_min_length (default 8), social_providers (default oauth_google, oauth_github), organizations_enabled (default true), hibp (breached password check, default on), test_mode (the 424242 code for +clerk_test addresses, default on in development), and support_email.
• oauth_applications: client_id, name, and redirect_uris (required), client_secret, scopes (defaults to openid profile email), public (skips the client secret check), consent_screen_enabled (see Consent screen). An entry for an existing client_id, such as the default clerk_baseline_client, updates it.
• jwt_templates: name and claims (required), lifetime, allowed_clock_skew, custom_signing_key, signing_algorithm, signing_key. A template whose name already exists is skipped. See Session tokens.

​

Inspector

• GET /_inspector shows users, sessions and clients, sign-in and sign-up attempts, sent codes, and the publishable keys.

​

Limits

​

Conformance