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
Change a role	Change a member's role
Remove a member	Remove a member
Invite people	Create invites
Change, resend or revoke an invite	Invites

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; 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.

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 returns the 50 most recent, newest first.