# Accounts, organisations and roles

Signing in to the panel, organisations and invitations, the five roles and what each may do, API key scopes, and two-factor authentication.

People sign in to the panel with their own account and act inside an organisation through a role; programs and scripts act through API keys with a scope. Both are judged against the same list of actions, so what a person may do in the panel and what a key may do through the API never disagree.

## When to use it

Read this page when you invite colleagues, decide who may approve proposals or see billing, create API keys for automation, or set up two-factor authentication. The organisation is the boundary for everything else: programs, jobs, sessions, credits and keys belong to one organisation, and nothing is shared between organisations.

## Signing in

The panel signs you in with an e-mail address and password (at least twelve characters, and not a commonly used one), a one-time link sent by e-mail, GitHub or Google. A password account has to confirm its address before it can act in an organisation.

Your first sign-in creates a personal organisation, owned by you, so that there is always somewhere to put a program. You can rename it, create more from the organisation switcher (**Create organisation**), and be invited into others.

## Invitations

An owner or admin invites by e-mail and role. The invitation is good for seven days, once, and only for the address it was sent to: whoever accepts it has to be signed in with that address. An organisation can send twenty invitations an hour.

## Roles

| | owner | admin | developer | reviewer | viewer |
|:--|:-:|:-:|:-:|:-:|:-:|
| Read programs, jobs, proposals, sessions, schedules, webhooks and usage | ✓ | ✓ | ✓ | ✓ | ✓ |
| Approve and reject proposals; take over, resume and cancel jobs | ✓ | ✓ | ✓ | ✓ | |
| Build and publish programs, move aliases, run jobs, manage sessions, schedules and webhooks | ✓ | ✓ | ✓ | | |
| See API keys and the audit log | ✓ | ✓ | ✓ | | |
| Create, rotate and revoke API keys | ✓ | ✓ | | | |
| Billing, bring-your-own providers, members and invitations, organisation settings | ✓ | ✓ | | | |
| Delete the organisation | ✓ | | | | |

Only an owner may make somebody an owner or an admin, and an organisation always keeps at least one owner. The last owner cannot leave.

A `reviewer` is the role for people who keep programs running without building them: they approve healing proposals, take over parked jobs and resume them, but cannot see keys or billing.

## API keys and scopes

An API key belongs to the organisation, not to the person who created it. It has a mode, `live` (`sk_live_…`) or `test` (`sk_test_…`), and one or more scopes:

| Scope | May |
|---|---|
| `read` | read everything a key may read: programs, jobs, proposals, sessions, schedules, the organisation, credits, usage |
| `run` | everything `read` may, plus create and act on jobs, write and publish programs, decide proposals, manage sessions and schedules |
| `admin` | everything, including keys, webhooks, bring-your-own providers and organisation settings; never members, and never deleting the organisation |

A key creates keys of its own mode only, and only an owner, an admin or an `admin` key grants `admin`. A refused request answers `403`. See [Keys and modes](https://docs.kaab.ist/getting-started/keys-and-modes) for creating, rotating and revoking keys.

A coding agent connected over MCP acts through an OAuth grant instead of a key: its permissions are the scopes you granted, limited by your own current role. See [MCP](https://docs.kaab.ist/guides/mcp).

## Two-factor authentication

Owners and admins need an authenticator app (TOTP) for the actions that matter most: keys, billing, members, bring-your-own providers, sessions and deleting the organisation. A new organisation's owners have seven days before this applies; after that, an owner or admin without it is refused those actions with `403 two_factor_required`. Creating, rotating or revoking a key, changing the organisation or the payment method, and deleting the organisation also ask for your password or a code again if you have not entered one in the last fifteen minutes (`403 reauth_required`).

Enrolling gives you ten backup codes; each works once.

## In the panel

Your account menu has **Profile**, **Security** and **API keys**; the organisation switcher has **Organisation settings** and **Create organisation**.

- **Security** shows **Two-factor authentication** ("a code from an authenticator app at every sign-in") with buttons for new backup codes and to turn it off, your **Password**, and **Sessions**: the browsers signed in to your account. An owner or admin who turns two-factor off is warned that keys, members and billing will be locked for them until they turn it on again.
- **Organisation** settings show the name, slug, region and plan; **Leave organisation**; and, for an owner, **Delete organisation**, which asks you to type the organisation's name and says that programs, jobs, results, snapshots, sessions and keys are deleted within 24 hours.
- **Members** lists everyone with their role and whether two-factor is on, lets an owner or admin change a role, and removes a member, who loses access at once.
- **Invitations** has an **Invite people** form (e-mail and role; "they get an e-mail with a link that works once, for seven days") and the pending invitations.

## Worked example

A team of three automates price checks on `https://shop.example.com`.

1. Ayşe signs up and gets a personal organisation; she renames it `acme-pricing` and turns on two-factor under **Security**, because as its owner she will need it for keys and billing.
2. She invites Deniz as `developer` and Mert as `reviewer`. Each gets an e-mail with a link that works once, for seven days, and only for that address.
3. Deniz builds the program, publishes it and puts it on a schedule. He can see the organisation's API keys but cannot create one, so Ayşe creates an `sk_live_` key with the `run` scope for their CI.
4. The site changes. A `relocate` proposal arrives, and Mert, as a reviewer, opens it under **Review** and approves it with **Promote**. He cannot see the billing page or the keys.
5. Later Deniz leaves the company. Ayşe removes him under **Members**; he loses access at once. The CI key keeps working, because it belongs to the organisation, not to Deniz.

## Pitfalls

- **Keys outlive people.** Removing a member does not revoke the keys they created. Rotate keys a departing person had access to.
- **A reviewer cannot run jobs.** Give `developer` to anyone who needs to create jobs, not only approve them.
- **Two-factor applies to owners and admins after seven days.** Enrol before the grace period ends, or keys, billing and members lock for you.
- **An `admin` key can do almost everything an admin can.** Use `run` for automation and keep `admin` keys for tooling that manages keys or webhooks.
- **Test keys run test jobs only.** A key's mode decides the job's mode; a request cannot override it.

## Reference

- [Roles](https://docs.kaab.ist/reference/codes#roles) and [key scopes](https://docs.kaab.ist/reference/codes#key-scopes)
- [Create an API key](https://docs.kaab.ist/reference/api/api-keys/create-api-key), [rotate](https://docs.kaab.ist/reference/api/api-keys/rotate-api-key), [revoke](https://docs.kaab.ist/reference/api/api-keys/revoke-api-key)
- [API key schema](https://docs.kaab.ist/reference/api/schemas/api-key) and [organisation schema](https://docs.kaab.ist/reference/api/schemas/org)
- [Security and data](https://docs.kaab.ist/guides/security-and-data)