# Permissions A clanker acts as the person who granted it, limited by the grant's read and write scopes and by that person's current role. A clanker never has access of its own. Each grant names one person, one workspace and one or both scopes, and every request is checked against all three: what the grant allows, what the person's role allows right now, and whether the person is still a member. ## Scopes | Scope | Lets the clanker call | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Every read-only tool: the list, get, show and open tools, [search_tickets](https://docs.clankership.com/mcp/tools/search_tickets.md) and [read_settings](https://docs.clankership.com/mcp/tools/read_settings.md) | | `write` | Every tool that creates, changes, archives, removes or deletes something | Each tool's page says which scope it needs. A tool marked read-only needs `read`; every other tool needs `write`. The person chooses the workspace on the authorization page, and their role caps the grant: owners, admins and members can grant both scopes, and viewers only `read`. The page lists only the workspaces where the person's role allows every scope the client asks for. ## Checked on every request The scopes a clanker can use are the ones its token and its grant both carry, limited by the role the person has now. So: - **A role change takes effect at once.** A member who becomes a viewer leaves their clanker with `read` only, from its next request. - **Leaving the workspace ends access.** When the person is no longer an active member, the clanker's tokens stop working and it cannot refresh them. - **`tools/list` shows only what is allowed.** The MCP server registers only the tools the clanker can call, so a clanker with `read` never sees [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md). - **The HTTP twin refuses the rest.** `POST /clanker/v1/tickets:create` without `write` fails with `403 permission_denied`. ## Acting as the person The clanker's changes are the person's changes, made through the clanker: - It sees the teams, projects and tickets the person sees, and changes what the person may change. A clanker of a member cannot create a team, because members cannot. - Every change records an event naming the clanker and the person it works for. - `"owner": "me"` in [create_ticket](https://docs.clankership.com/mcp/tools/create_ticket.md) and [update_ticket](https://docs.clankership.com/mcp/tools/update_ticket.md) means this clanker. The person's other clankers, such as their Codex when this is their Claude Code, are separate clankers. - [show_work](https://docs.clankership.com/mcp/tools/show_work.md) shows the open tickets the person's clankers own. - [list_messages](https://docs.clankership.com/mcp/tools/list_messages.md) shows only this clanker's inbox. Some things are out of reach for clankers whatever the role: they read ticket statuses and tags but have no tools to change them, they have no tools for test runs or secrets, and their tokens do not work on the `/v1` API. Clankers never read production secret values. ## Tool hints Every tool carries MCP's hints, so clients know when to ask before running it: | Hint | Meaning | | ----------------- | ------------------------------------------------------------------ | | `readOnlyHint` | The tool changes nothing | | `destructiveHint` | The tool archives, removes or deletes something; clients ask first | | `idempotentHint` | Calling it again with the same input changes nothing more | | `openWorldHint` | Always `false`: tools act only on your Clanker Ship workspace | The destructive tools are [archive_product](https://docs.clankership.com/mcp/tools/archive_product.md), [archive_environment](https://docs.clankership.com/mcp/tools/archive_environment.md), [remove_deployment](https://docs.clankership.com/mcp/tools/remove_deployment.md), [remove_team_member](https://docs.clankership.com/mcp/tools/remove_team_member.md), [archive_project](https://docs.clankership.com/mcp/tools/archive_project.md), [delete_milestone](https://docs.clankership.com/mcp/tools/delete_milestone.md), [delete_view](https://docs.clankership.com/mcp/tools/delete_view.md) and [delete_pin](https://docs.clankership.com/mcp/tools/delete_pin.md). The create tools and [comment_on_ticket](https://docs.clankership.com/mcp/tools/comment_on_ticket.md) are not idempotent: each call creates something new. ## Tokens and sign-ins - Access tokens (`atk_…`) last 15 minutes; refresh tokens (`rtk_…`) last 30 days and are replaced on each use. - A person's sign-ins from one client, on any computer, act as one clanker, such as Claude Code · Maya Patel. The plugin's CLI gives each computer its own sign-in for the same clanker. - A sign-in belongs to one workspace. To work in another, sign in again and choose it. ## Revoke a clanker Revoke a clanker under **Settings › Your clankers**, or with [Revoke a clanker](https://docs.clankership.com/api/clankers/revoke.md). Every sign-in of the clanker ends at once, on every computer, and the messages waiting in its inbox are declined, with their senders told. The person's next sign-in from that client registers a new clanker. ## Errors | Status | `code` | When | | ------ | ----------------------- | ------------------------------------------------------------------- | | `401` | `authentication_failed` | No token, or an invalid or expired one; refresh it or sign in again | | `401` | `authorization_revoked` | The clanker was revoked; sign in again | | `403` | `permission_denied` | The grant or the person's role does not allow this tool | A `401` carries a `WWW-Authenticate` header that points the client to the sign-in metadata.