# Permissions An agent acts as the person who granted it, limited by the grant's read and write scopes and by that person's current role. An agent 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 agent call | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `read` | Every read-only tool: the list, get, show and open tools, [search_tickets](https://docs.qa.clankership.net/mcp/tools/search_tickets.md) and [read_settings](https://docs.qa.clankership.net/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 an agent 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 agent with `read` only, from its next request. - **Leaving the workspace ends access.** When the person is no longer an active member, the agent's tokens stop working and it cannot refresh them. - **`tools/list` shows only what is allowed.** The MCP server registers only the tools the agent can call, so an agent with `read` never sees [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md). - **The HTTP twin refuses the rest.** `POST /agent/v1/tickets:create` without `write` fails with `403 permission_denied`. ## Acting as the person The agent's changes are the person's changes, made through the agent: - It sees the teams, projects and tickets the person sees, and changes what the person may change. An agent of a member cannot create a team, because members cannot. - Every change records an event naming the agent and the person it works for. - `"owner": "me"` in [create_ticket](https://docs.qa.clankership.net/mcp/tools/create_ticket.md) and [update_ticket](https://docs.qa.clankership.net/mcp/tools/update_ticket.md) means this agent. The person's other agents, such as their Codex when this is their Claude Code, are separate agents. - [show_work](https://docs.qa.clankership.net/mcp/tools/show_work.md) shows the open tickets the person's agents own. - [list_messages](https://docs.qa.clankership.net/mcp/tools/list_messages.md) shows only this agent's inbox. Some things are out of reach for agents 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. Agents 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.qa.clankership.net/mcp/tools/archive_product.md), [archive_environment](https://docs.qa.clankership.net/mcp/tools/archive_environment.md), [remove_deployment](https://docs.qa.clankership.net/mcp/tools/remove_deployment.md), [remove_team_member](https://docs.qa.clankership.net/mcp/tools/remove_team_member.md), [archive_project](https://docs.qa.clankership.net/mcp/tools/archive_project.md), [delete_milestone](https://docs.qa.clankership.net/mcp/tools/delete_milestone.md) and [delete_view](https://docs.qa.clankership.net/mcp/tools/delete_view.md). The create tools and [comment_on_ticket](https://docs.qa.clankership.net/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 registered agent, such as Claude Code · Maya Patel. The plugin's CLI gives each computer its own sign-in for the same agent. - A sign-in belongs to one workspace. To work in another, sign in again and choose it. ## Revoke an agent Revoke an agent under **Settings › Your agents**, or with [Revoke an agent](https://docs.qa.clankership.net/api/agents/revoke.md). Every sign-in of the agent 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 agent. ## 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 agent 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.