# Workspaces and roles

A workspace holds a company's work and people, and each member's role decides what they and their agents can do.

A workspace holds a company's products and environments, its teams, projects and tickets, its test
runs and secrets, and the people who work on them. Every other object belongs to exactly one
workspace. API paths name it by its slug or its ID, such as `/v1/workspaces/acme`.

## Slugs

A workspace slug is 2 to 48 lowercase letters, digits and hyphens, with no hyphen at the start or
end, such as `acme`. Owners and admins can change it under **Settings › Workspace**. API paths take
the workspace ID too, which never changes, so a script that stores the ID keeps working after a
rename. The `clanker link` command stores the ID for the same reason.

## Roles

Each member has one role. Agents act with their person's role, and account API keys with the role
they were given.

| Role   | Can                                                                                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner  | Everything an admin can, plus give or take the owner role and manage owner account API keys                                                                                                       |
| Admin  | Manage the workspace, its people, invites, teams, ticket statuses, workspace tags, vault keys and production secrets                                                                              |
| Member | Do the work: create and change products, environments, deployments, tickets and projects; change their teams' views, tags and agent instructions; publish test runs; write non-production secrets |
| Viewer | Read everything they can see, and join open teams                                                                                                                                                 |

Each concept page lists the exact rules for its objects, such as who may change a team's tags or
restore a production secret.

- Admins cannot change an owner's role, make anyone an owner, or remove an owner.
- The last owner cannot be demoted or removed, and nobody can remove themselves.
- A viewer's agent can only read, because a viewer can grant only the `read` scope.

## Members and invites

Owners and admins invite people from **Settings › Members** with **Invite member**. An invite asks
one email address to join with a role and, optionally, teams. Its emailed link expires after 7
days; resending sends a fresh link and the old one stops working. The person accepts with the same
email address the invite was sent to.

**Allowed domains** on **Settings › Workspace** list email domains, such as `acme.dev`. When they
are set, invites must use one of them, and anyone who signs in with an address on one of them joins
the workspace as a member automatically. With no allowed domains, invites may use any address.

| Operation                          | API                                           |
| ---------------------------------- | --------------------------------------------- |
| List members                       | [List members](https://docs.qa.clankership.net/api/members/list.md)             |
| Change a role                      | [Change a member's role](https://docs.qa.clankership.net/api/members/update.md) |
| Remove a member                    | [Remove a member](https://docs.qa.clankership.net/api/members/remove.md)        |
| Invite people                      | [Create invites](https://docs.qa.clankership.net/api/invites/create.md)         |
| Change, resend or revoke an invite | [Invites](https://docs.qa.clankership.net/api/invites.md)                       |

## Account API keys

An account API key belongs to the workspace instead of a person, so CI keeps working when people
come and go. It acts with the role it was given. Owners and admins create them under
**Settings › Security › Account API keys**, or with
[Create an account API key](https://docs.qa.clankership.net/api/account-api-keys/create.md); only owners create or manage keys with
the owner role. The key's value is shown once.

```bash
curl https://api.clankertest.com/v1/workspaces/acme/account-api-keys \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Release CI", "role": "member" }'
```

```json
{
  "id": "Ak2WqH9sDf5T",
  "name": "Release CI",
  "role": "member",
  "secret": "ctk_4mT8vQ2xR7nL9pW3kS6dH1jF5bY0cZaE"
}
```

An account API key can do what a person in its role can, except what belongs to a person: it
cannot change a profile, create or list user API keys, create workspaces, register agents, send
messages to agents or comment on tickets. See [Authentication](https://docs.qa.clankership.net/api/authentication.md).

## Events

Every change records an event naming the person, the agent and its person, or the account API key
that made it. Any member reads them on the workspace's **Events** page.
[List events](https://docs.qa.clankership.net/api/events/list.md) returns the 50 most recent, newest first.