Skip to main content
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. Important: Changes take effect immediately with up to 30-second edge propagation.

​
Required Permissions

Your root key must have one of the following permissions:
  • api.*.update_key (to update keys in any API)
  • api.<api_id>.update_key (to update keys in a specific API)

​
Side Effects

Invalidates the key cache for immediate effect, and makes permissions available for verification within 30 seconds across all regions.

​
Request

​
keyId
string
required
Specifies which key receives the additional permissions using the database identifier returned from keys.createKey.Do not confuse this with the actual API key string that users include in requests.Pattern: ^[a-zA-Z0-9_]+$Example: key_2cGKbMxRyIzhCxo1Idjz8q
​
permissions
array
required
Grants additional permissions to the key through direct assignment or automatic creation.Duplicate permissions are ignored automatically, making this operation idempotent.Adding permissions never removes existing permissions or role-based permissions.Any permissions that do not exist will be auto created if the root key has permissions, otherwise this operation will fail with a 403 error.Pattern: ^[a-zA-Z0-9_:\-\.\*]+$Min items: 1Max items: 1000Example: ["documents.read", "documents.write"]

​
Response

​
permissions
array
required
Complete list of all permissions directly assigned to the key (including both newly added permissions and those that were already assigned).Important: This list does NOT include permissions granted through roles. For a complete permission picture, use keys.getKey instead.An empty array indicates the key has no direct permissions assigned.

​
Examples

curl -X POST https://api.unkey.com/v2/keys.addPermissions \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_1234abcd",
    "permissions": ["documents.read", "documents.write"]
  }'

​
Response Example

{
  "meta": {
    "requestId": "req_abc123def456"
  },
  "data": [
    {
      "id": "perm_123",
      "name": "documents.read"
    },
    {
      "id": "perm_124",
      "name": "documents.write"
    },
    {
      "id": "perm_125",
      "name": "settings.view"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us