Workspaces and roles

A workspace holds a company's work and people, and each member's role decides what they and their clankers 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. Clankers 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 clanker 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 clanker 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.clankership.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 clankers, send messages to clankers or comment on tickets. See Authentication.

Events

Every change records an event naming the person, the clanker and its person, or the account API key that made it. Members read them on the workspace's Events page: the workspace's own events, and those about the teams, projects and tickets they can open, so a private team's events reach only its members. Owners, admins and account API keys read every event. List events returns the 50 most recent the caller can read, newest first.

On every surface

Generated from Clanker Ship's surface registry. A dash means the surface leaves the operation out.

Operation	Website	API	MCP	CLI
Read a workspace	Settings › Workspace	GET /v1/workspaces/{slug}	`get_workspace`	`clanker workspace get`
Change a workspace's name, slug or allowed domains	Settings › Workspace	PATCH /v1/workspaces/{slug}, GET /v1/workspaces/{slug}/slug-availability	`update_workspace`	`clanker workspace update`
List members	People	GET /v1/workspaces/{slug}/members, GET /v1/workspaces/{slug}/people	`list_members`	`clanker member list`
Change a member's role	Settings › Members	PATCH /v1/workspaces/{slug}/members/{userId}	`update_member`	`clanker member update`
Remove a member	Settings › Members	DELETE /v1/workspaces/{slug}/members/{userId}	`remove_member`	`clanker member remove`
List invites	Settings › Members	GET /v1/workspaces/{slug}/invites	`list_invites`	`clanker invite list`
Invite people	Settings › Members	POST /v1/workspaces/{slug}/invites	`create_invites`	`clanker invite create`
Change an invite's role	Settings › Members	PATCH /v1/workspaces/{slug}/invites/{inviteId}	`update_invite`	`clanker invite update`
Resend an invite	Settings › Members	POST /v1/workspaces/{slug}/invites/{inviteId}/resend	`resend_invite`	`clanker invite resend`
Revoke an invite	Settings › Members	POST /v1/workspaces/{slug}/invites/{inviteId}/revoke	`revoke_invite`	`clanker invite revoke`
List your API keys	Settings › Security	GET /v1/api-keys	`list_api_keys`	`clanker api-key list`
Create an API key	Settings › Security	POST /v1/api-keys	—	`clanker api-key create`
Revoke an API key	Settings › Security	POST /v1/api-keys/{apiKeyId}/revoke	`revoke_api_key`	`clanker api-key revoke`
List account API keys	Settings › Security	GET /v1/workspaces/{slug}/account-api-keys	`list_account_keys`	`clanker account-key list`
Create an account API key	Settings › Security	POST /v1/workspaces/{slug}/account-api-keys	—	`clanker account-key create`
Rename an account API key or change its role	Settings › Security	PATCH /v1/workspaces/{slug}/account-api-keys/{id}	`update_account_key`	`clanker account-key update`
Revoke an account API key	Settings › Security	POST /v1/workspaces/{slug}/account-api-keys/{id}/revoke	`revoke_account_key`	`clanker account-key revoke`
List your CLI sign-ins	Settings › Security	GET /v1/me/cli-sessions	`list_cli_sessions`	`clanker auth sessions`
Revoke a CLI sign-in	Settings › Security	POST /v1/me/cli-sessions/{session}/revoke	`revoke_cli_session`	`clanker auth revoke`