add-permissions

Add permissions to a key without affecting existing permissions. Use this for privilege upgrades, enabling new features, or plan changes that grant additional capabilities. Permissions granted through roles remain unchanged. Duplicate permissions are ignored automatically, making this operation idempotent. Important: Changes take effect immediately with up to 30-second propagation across regions. Any permissions that do not exist will be auto-created if the root key has the required permissions. Required permissions:

api.*.update_key (to update keys in any API)
api.<api_id>.update_key (to update keys in a specific API)

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api keys add-permissions [flags]

Flags

string

required

The key ID to add permissions to. This is the database identifier returned from keys.createKey (e.g., key_2cGKbMxRyIzhCxo1Idjz8q). Do not confuse this with the actual API key string that users include in requests.

string[]

required

Comma-separated list of permission names to add. Adding permissions never removes existing permissions or role-based permissions. Duplicate permissions are ignored automatically. Permissions that do not yet exist will be auto-created if the root key has permissions, otherwise the operation will fail with a 403 error.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format. Use `json` for raw JSON
`--body`	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

unkey api keys add-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write

unkey api keys add-permissions --key-id=key_1234abcd --permissions=billing.manage --output=json

unkey api keys add-permissions --key-id=key_1234abcd --permissions=admin.read,admin.write,admin.delete

Output

Default output shows the request ID, followed by the permissions now assigned to the key:

req_2c9a0jf23l4k567

[
  {
    "id": "perm_1234567890abcdef",
    "name": "documents.read",
    "slug": "documents.read"
  },
  {
    "id": "perm_abcdef1234567890",
    "name": "documents.write",
    "slug": "documents.write"
  }
]

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "perm_1234567890abcdef",
      "name": "documents.read",
      "slug": "documents.read"
    },
    {
      "id": "perm_abcdef1234567890",
      "name": "documents.write",
      "slug": "documents.write"
    }
  ]
}

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Usage

Flags

Global Flags

Examples

Output

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output