code: INSUFFICIENT_PERMISSIONS and no rate limit or credits are used.
The pieces
A permission is a string you define, such asdocuments.read or billing:write. It has a readable name, a slug that keys and queries use, and an optional description. It means whatever your API decides it means.
A role is a named group of permissions, such as editor with documents.read and documents.write. A key with the role gets all its permissions, and changing the role changes every key that has it.
A key can have permissions, roles, or both. Its permissions are its own plus those from its roles. Verification returns them as data.permissions, and the roles as data.roles.
A permission query is what you send as permissions on keys.verifyKey: one slug, or slugs combined with AND, OR, and parentheses. Verification passes only if the key’s permissions satisfy it.
Key permissions vs root key permissions
The permissions on this page belong to your users’ keys, and your API decides what they allow. Root key permissions, such asapi.*.create_key, control what your root keys can do on api.unkey.com. The two never mix. See Root key permissions.
When to check where
Send apermissions query when the answer depends only on the key: “can this key write documents?” Unkey answers as part of the verification. Check data.permissions in your own code when the answer also depends on your data: “can this key delete this document?” needs the document’s owner, which Unkey doesn’t know.
Next steps
Roles and permissions
Create permissions and roles through the API or the dashboard, with slug rules and bounds.
Permission queries
The query grammar, its limits, and why an asterisk isn’t a wildcard.
Managing key roles and permissions
Attach, replace, and remove roles and permissions on a key.
Verifying keys
Where the permission check sits among the other verification checks.