Sign in
keys

Add key roles

Add roles to a key without affecting existing roles or permissions.

Use this for privilege upgrades, enabling new feature sets, or subscription changes that grant additional role-based capabilities. Direct permissions 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 role assignments available for verification within 30 seconds across all regions.

post/v2/keys.addRoles

Request body

keyIdstring required

Specifies which key receives the additional roles using the database identifier returned from createKey. Do not confuse this with the actual API key string that users include in requests. Added roles supplement existing roles and permissions without replacing them. Role assignments take effect immediately but may take up to 30 seconds to propagate across all regions.

rolesstring[] required

Assigns additional roles to the key through direct assignment to existing workspace roles. Operations are idempotent - adding existing roles has no effect and causes no errors.

All roles must already exist in the workspace - roles cannot be created automatically. Invalid roles cause the entire operation to fail atomically, ensuring consistent state.

Example request

{
  "keyId": "key_2cGKbMxRyIzhCxo1Idjz8q"
}

Response

Roles added successfully. Returns all roles currently assigned to the key.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "role_1234567890abcdef",
      "name": "support.readonly",
      "description": "Provides read-only access for customer support representatives to view user accounts and support tickets",
      "permissions": [
        {
          "id": "perm_1234567890abcdef",
          "name": "users.read",
          "slug": "users-read",
          "description": "Allows reading user profile information and account details"
        }
      ]
    }
  ]
}

Changes

Changed in 5 of the 90 revisions of this API.17

  • 4bd11a7252bc12See the full diff
    • ▲

      the roles/items/ request property's maxLength was decreased to 128

      request-property-max-length-decreased

    • ○

      the roles/items/ request property's minLength was decreased from 3 to 1

      request-property-min-length-decreased

    • ○

      removed the pattern ^[a-zA-Z][a-zA-Z0-9._-]*$ from the request property roles/items/

      request-property-pattern-removed

  • 43ad1ce9a1522See the full diff
    • ○

      the endpoint scheme security dashboard was removed from the API

      api-security-removed

    • ○

      the endpoint scheme security rootKey was removed from the API

      api-security-removed

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1f6cb66aa3df1See the full diff
    • ○

      the endpoint scheme security dashboard was added to the API

      api-security-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 551df53dd45d1See the full diff
    • ○

      added the non-success response with the status 429

      response-non-success-status-added

  • 9a9c22b6dd091See the full diff
    • ○

      api operation id addRoles removed and replaced with keys.addRoles

      api-operation-id-removed