Clerk Connections

Clerk connections let agents call Clerk’s Backend API to inspect users, organizations, sessions, and invitations. Authentication uses a Clerk Secret Key as a Bearer token.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Setup

Open the Clerk Dashboard for the instance you want to connect
Navigate to API Keys
Copy the Secret Key — it starts with sk_live_ (production) or sk_test_ (development)

Connection Parameters

Authentication

Clerk’s API uses a single Bearer-token auth scheme.

"bearer_token": {
  "token": "sk_live_..."
}

Optional Parameters

Parameter	Type	Description	Default
`read_only`	bool	Advisory hint to the agent that only `GET` requests are allowed	`false`

read_only is advisory — it surfaces in the agent’s connection prompt and the OpenAPI calling skill, steering the agent toward GET-only usage. It is not enforced by the network proxy or the shell environment, so a Clerk Secret Key with write permissions can still issue mutating requests if the agent ignores the hint. Scope the API key itself to read-only when you need a hard guarantee.

Example Connection

{
  "display_name": "Production Clerk",
  "description": "Production Clerk instance — user/org lookup for incident response",
  "connection_details": {
    "clerk": {
      "bearer_token": { "token": "sk_live_..." },
      "read_only": true
    }
  }
}

Description Field

Document which Clerk instance this is and what it’s used for. Useful pointers for agents:

Production Clerk instance for app.example.com.

Common workflows:
- User lookup by email → GET /v1/users?email_address=<email>
- Organization membership → GET /v1/organizations/{org_id}/memberships
- Recent sessions for a user → GET /v1/sessions?user_id=<user_id>

Best Practices

Enable read_only: true for incident-response and customer-support agents — they almost never need to write to Clerk
Use sk_test_* keys for non-production deployments so agent activity in dev is isolated from production user data
Rotate keys after personnel changes — Clerk Secret Keys grant full backend access; treat them like database admin credentials