# Organizations, members and roles

> An organization owns domains, members and tokens. Learn the four roles, client scopes and how the effective role of a request is computed.

Everything in OpenWAF belongs to an **organization**: its domains (zones), its [clients](https://developers.openwaf.dev/fundamentals/agencies-and-clients/),
its members, its API tokens, its brand and its audit log. A person can be a member of several organizations; the
dashboard's **Switch organization** menu moves between them.

## Roles

Every member has one role in the organization. Roles are ordered: each one can do everything the roles below it can.

| Role | Dashboard name | What it adds |
|---|---|---|
| `readonly` | Read only | Sees domains, records, settings, rules, history, certificates and metrics. Changes nothing. |
| `tech` | Tech | Adds and deletes domains and changes their configuration: DNS records, edge settings, rules, certificates, cache purges, delegation checks. Creates clients and assigns domains to them. |
| `admin` | Admin | Manages members (except owners) and invitations, sees and revokes every API token, edits and deletes clients, reads the audit log, manages the white label and merges zones. |
| `owner` | Owner | Everything, including giving and taking away the owner role. |

Some actions need a credential that covers the **whole organization** (not limited to one client or one domain):
managing members, clients, tokens of others, the white label and the audit log, and assigning domains to clients.

An organization always keeps at least one owner: removing or demoting the last owner is refused with `409 conflict`.

## Client scope

A member can be **limited to one client**. A client-scoped member only sees and manages the domains assigned to that
client, and can only have the `tech` or `readonly` role. Domains they add are assigned to their client automatically.
See [Agencies and clients](https://developers.openwaf.dev/fundamentals/agencies-and-clients/).

## Effective role

Every request is authorised with an **effective role** and an **effective scope**, computed when the request arrives:

- **Dashboard session**: the role and client scope of your membership in the organization you are working in.
- **API token** (also tokens created when you connect an AI assistant through OAuth): the role of the token, capped by
  the current role of the member who created it. If that member is later demoted, their tokens are demoted with them;
  if the member is removed, their tokens are revoked.
- **Scope**: a token limited to one domain only sees that domain. A token of a client-scoped member is always limited
  to that member's client, even if it was created before the member was limited.

```text
effective role  = lower of (token role, member's current role)
effective scope = token scope, narrowed to the member's client if the member is client-scoped
```

For example, an admin creates a `tech` token for CI. The token works with `tech` permissions. If the admin is later
changed to `readonly`, the token can only read. See [API tokens](https://developers.openwaf.dev/fundamentals/api-tokens/).

A request without enough permission gets `403 forbidden`. A domain outside your scope answers `404 not_found`, as if
it did not exist.

## Organization settings

| Setting | Who can change it | Where |
|---|---|---|
| Organization name | Admin | API: `PATCH /v1/orgs/{org}` with `{"name": "…"}` |
| Members and invitations | Admin (owners: Owner) | **Members** — see [Team members](https://developers.openwaf.dev/fundamentals/team-members/) |
| API tokens | Anyone (their own); Admin (all) | **API tokens** — see [API tokens](https://developers.openwaf.dev/fundamentals/api-tokens/) |
| Clients | Tech creates; Admin edits and deletes | **Clients** — see [Agencies and clients](https://developers.openwaf.dev/fundamentals/agencies-and-clients/) |
| Brand, dashboard domain, nameservers | Admin | **White label** — see [White-label dashboard](https://developers.openwaf.dev/fundamentals/white-label/) |
| Audit log | Admin (client-scoped Tech: their client's domains) | **Audit log** |

## Audit log

The audit log lists every change made in the organization, newest first: who made it (a user, a token or the system),
the action and its target. It records changes from the dashboard, the API, the CLI and the MCP server alike.
Configuration changes of a domain are also kept as [zone versions](https://developers.openwaf.dev/dns/zone-versions/).