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

# People and access

> Manage workspace members, roles, API keys, and what each person can do.

Access in Kordless is built on Clerk Organizations. One Organization maps to one Kordless account. The people in your Organization are the people in your workspace — there is no separate invite system or user table to manage.

## Two roles

Your Clerk Organization has two roles that Kordless recognizes:

| Role   | Who they are                                 | What they can do                                                                                                                                 |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Admin  | Organization admins (`org:admin` in Clerk)   | Everything members can do, plus: manage billing, mint and revoke API keys, configure webhooks, and manage Organization membership through Clerk. |
| Member | Organization members (`org:member` in Clerk) | Operate the workspace: author and verify the Book, review quotes, manage commitments, configure settings, and view usage.                        |

<Info>
  Roles are managed in Clerk, not in Kordless. To invite someone or change their role, use your Clerk Organization settings. Kordless reads the role from the active session — there is no separate role database to keep in sync.
</Info>

## What admins can do that members cannot

The following operations require an admin:

* **Billing** — Choosing or changing a plan, pausing Live use, and accessing the Stripe portal.
* **API keys** — Minting, rolling, and revoking API keys. Secrets are shown once at creation or rotation.
* **Webhooks** — Creating, updating, and deleting webhook endpoints.
* **Stripe Connect** — Starting or resuming Stripe Connect onboarding for deposits and payouts.

Everything else — authoring the Book, reviewing quotes, approving or correcting results, configuring settings, and managing commitments — is available to any member of the Organization.

## Workspace relationships

When your account connects to another account (a third-party account or a managed workspace), the connection carries a relationship that determines what the connected party can operate:

| Relationship | What it means                                                                                           |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| Owner        | Full operational surface. This is the default for your own directly operated workspace.                 |
| Manager      | Full operational surface, same as owner.                                                                |
| Integrator   | The developer channel only: API access, quoting, and the Book. Cannot operate hosted merchant surfaces. |
| Viewer       | Read-only. Can see everything but operates nothing.                                                     |

<Info>
  Today, every directly operated workspace uses the owner relationship. The integrator and viewer relationships are part of the connected-accounts model, which is used when your account integrates with or views another account's Book.
</Info>

## API keys

API keys are machine credentials for integrating the verified Book from your own code. They are managed on the Developers page.

### Key properties

| Property    | Description                                                                                |
| ----------- | ------------------------------------------------------------------------------------------ |
| Environment | `test` or `live`. Test keys reach only test data; live keys reach production.              |
| Scopes      | A subset of the available API scopes (see below).                                          |
| Secret      | Shown once at creation or rotation. Only the SHA-256 hash and a display prefix are stored. |
| Status      | `active`, `rotating` (during a grace period), or `revoked`.                                |

### Available scopes

| Scope               | What it allows                                           |
| ------------------- | -------------------------------------------------------- |
| `accounts:read`     | Read account and workspace information.                  |
| `quote-spec:read`   | Read the published Book specification.                   |
| `simulations:write` | Run pricing simulations (non-persistent, never metered). |
| `quotes:write`      | Produce quotes through the API.                          |
| `commitments:write` | Create and manage commitments.                           |
| `logs:read`         | Read API request logs.                                   |

### Key rotation

When you roll a key, Kordless creates a new key with the same name, environment, and scopes, and schedules the old key for revocation after a grace period:

* **Default grace**: 24 hours.
* **Maximum grace**: 168 hours (7 days).
* **Immediate rotation**: Set grace to 0 hours.

During the grace period, both keys work. After it expires, the old key stops accepting requests. This lets you update your integrations without downtime.

### Key revocation

Revoking a key kills it immediately. The revocation timestamp is preserved — if the key was already revoked, the original timestamp is kept.

<Warning>
  Only an admin can mint, roll, or revoke API keys. Members can view keys and their health but cannot manage them.
</Warning>

## Webhooks

Webhook endpoints receive commitment events at your own URLs. Each delivery is signed with an `X-Kordless-Signature` header that you verify against the endpoint's secret. Webhook management — creating, updating, rolling secrets, and deleting endpoints — requires an admin.

## Permission messages

When a member tries to do something that requires an admin, they see a message that names the action and the required authority — for example, "Only an organization admin can manage API keys." The message never explains database relationships or internal architecture.

## What access does not control

* **Pricing correctness** — Every tier grants the same core-correctness surface. Access does not gate the evaluator, authoring, verification, or replay.
* **Customer data** — Customer and vehicle records are contextual to the workspace, not gated by role beyond the admin/member split.
* **Test mode** — Any member can use Test mode. Test keys and data are fully isolated from Live.