---
title: Permissions
description: What an API key can be granted, and what only a member can do.
sidebar:
  order: 2
---

An API key's authority is exactly the set of permissions it was minted with. `subako api-key permissions` reads the live set from the server; the table below is what it holds today.

## Grantable to a key

| Permission | Allows |
| --- | --- |
| `workspace.read` | Read the workspace. |
| `agent.read` | Read agents and their versions. |
| `agent.publish` | Publish a new agent version. |
| `agent.delete` | Delete an agent, its versions, and its sessions. |
| `session.create` | Create sessions. |
| `session.read` | Read sessions and their event logs. |
| `session.manage` | Append input, cancel a run, and manage clients. |
| `vault.read` | Read vaults. |
| `vault.manage` | Create, update, and delete vaults. |
| `credential.read` | List credentials — never their payloads. |
| `credential.manage` | Add and delete credentials. |
| `skill.read` | Read skills and their versions. |
| `skill.manage` | Create, push, rename, and delete skills. |
| `model_provider.read` | Read model providers. |
| `model_provider.manage` | Create, update, and delete model providers. |

## Never grantable to a key

These are held by people, not machines. A key cannot be minted with them at all:

| Permission | Why |
| --- | --- |
| `workspace.members.read` | Membership is a human question. |
| `workspace.members.manage` | A key that can add members can grant itself a team. |
| `api_key.read` | A key that can enumerate keys can map the whole surface. |
| `api_key.manage` | A key that can mint keys can escalate past its own grant. |
| `usage.read` | Billing visibility belongs to a member. |

## A typical backend key

Most products need three:

```bash
subako api-key mint \
  --label "support-triage backend" \
  --permission session.create \
  --permission session.read \
  --permission session.manage
```

Nothing here can publish an agent version, read a vault, or touch a skill. A deploy pipeline that publishes versions is a separate key with `agent.publish`, and neither one can mint the other.

:::warning
`--all-permissions` grants everything the server allows a key to hold **as of mint time**. A permission added to that set later is not granted retroactively — which makes the flag convenient for a scratch key and a poor fit for anything long-lived.
:::

## Organization permissions

Organization-level authority — members, invitations, credits, usage, workspace creation — is carried by a membership role rather than by a key. `admin` holds it, `member` does not.

```txt
org.read              org.manage
org.members.read      org.members.manage
invitation.read       invitation.manage
org.credits.read      org.usage.read
workspace.create
```