> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Clerk

> A stateful replica of Clerk's Backend API v1: users, organizations and memberships, invitations and sessions for one application instance.

The Clerk replica implements 32 endpoints of the Backend API v1 for one application instance with email sign-in. Its key is `clerk`. It was tested with `@clerk/backend`.

## Connect

| Variable | Value |
| - | - |
| `CLERK_API_URL` | Base URL. Paths start with `/v1/`. |
| `CLERK_SECRET_KEY` | Fake secret key. Send `Authorization: Bearer <key>`. |

```js Node theme={null}
import { createClerkClient } from '@clerk/backend';
const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY, apiUrl: process.env.CLERK_API_URL });
const { data: users } = await clerk.users.getUserList({ limit: 10 });
```

This is what `ancha connect clerk --lang ts` prints.

## Endpoints

All 32 endpoints are partial. Anything else returns HTTP 501 with Clerk's error shape and `x-ancha-gap: 1`.

### Users

| Method | Path | Notes |
| - | - | - |
| `GET` | `/v1/users` | `email_address`, `user_id`, `username`, `external_id`, `organization_id`, `query`, name, email and username queries, `banned`, activity and creation windows, `order_by`, `limit` and `offset`. |
| `GET` | `/v1/users/count` | |
| `POST` | `/v1/users` | One email address per user. Password length and breached-password checks. Phone numbers, web3 wallets and imported hashes are gaps. |
| `GET`, `PATCH`, `DELETE` | `/v1/users/{user_id}` | |
| `PATCH` | `/v1/users/{user_id}/metadata` | Deep merge; `null` removes a key. |
| `POST` | `/v1/users/{user_id}/ban` | Revokes the user's active sessions. |
| `POST` | `/v1/users/{user_id}/unban`, `lock`, `unlock` | |
| `GET` | `/v1/users/{user_id}/organization_memberships` | |

### Organizations

| Method | Path | Notes |
| - | - | - |
| `GET` | `/v1/organizations` | `query`, `order_by` (`name`, `created_at`, `members_count`), `include_members_count`, `user_id`. |
| `POST` | `/v1/organizations` | |
| `GET` | `/v1/organizations/{organization_id}` | By ID or slug. |
| `PATCH`, `DELETE` | `/v1/organizations/{organization_id}` | |
| `PATCH` | `/v1/organizations/{organization_id}/metadata` | |
| `GET`, `POST` | `/v1/organizations/{organization_id}/memberships` | Members and pending invitations share `max_allowed_memberships`. |
| `PATCH`, `DELETE` | `/v1/organizations/{organization_id}/memberships/{user_id}` | |
| `GET`, `POST` | `/v1/organizations/{organization_id}/invitations` | Recorded, never emailed. Pending invitations expire after `expires_in_days`, 30 by default. |
| `GET` | `/v1/organizations/{organization_id}/invitations/{invitation_id}` | |
| `POST` | `/v1/organizations/{organization_id}/invitations/{invitation_id}/revoke` | |

### Invitations and sessions

| Method | Path | Notes |
| - | - | - |
| `GET`, `POST` | `/v1/invitations` | Instance-level invitations. |
| `POST` | `/v1/invitations/{invitation_id}/revoke` | |
| `GET` | `/v1/sessions` | `user_id` or `client_id` is required. |
| `GET` | `/v1/sessions/{session_id}` | |
| `POST` | `/v1/sessions/{session_id}/revoke` | |

## Starter data

The `clerk-starter` dataset is the instance **Acme dashboard**: the customers' users and organizations.

| Organization | Plan | Members |
| - | - | - |
| Ridgeway Robotics (`ridgeway-robotics`) | pilot, until 2026-11-30 | Erin Walsh (admin), Hector Ruiz, Bao Tran. Three pending invitations. |
| Pinecrest Health (`pinecrest-health`) | enterprise, 120 seats from 2026-12-01 | Helen Brooks (admin), Omar Haddad, Grace Liu. |
| Kestrel Credit Union (`kestrel-credit-union`) | business, renewal 2026-11-07 | Dale Whitfield (admin), Nina Alvarez (locked). |
| Summit Freight (`summit-freight`) | business | Carla Diaz (admin), Pete Novak. One pending invitation. |
| Helix Manufacturing (`helix-manufacturing`) | business, renewal 2026-12-15 | Ivan Petrov (admin). |

Twelve users in all, including Laura Kim from Acme with `staff: true` in her public metadata. Erin Walsh's private metadata links her to HubSpot contact `30001`. One instance-level invitation to `security@bluefield-logistics.example` is pending.

## Checks

Clerk has no state checks. Use trace checks, for example `{ called: "POST /v1/organizations/*/invitations" }` or `{ not_called: "DELETE /v1/users/*" }`.

## Limits

* One application instance with email sign-in; phone numbers, web3 wallets, SAML and imported password hashes are coverage gaps.
* Invitations are recorded, never emailed; pending ones expire on the scene clock.
* Session tokens and JWT verification are not modeled; sessions can be listed and revoked.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.