> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization Overview
> Control what each API key can access using role-based access control (RBAC). Assign roles and fine-grained permissions to your keys.
Authorization controls *what* an authenticated key can do. While verification answers "is this key valid?", authorization answers "can this key perform this action?"
Unkey provides Role-Based Access Control (RBAC) that lets you:
* Define **permissions** (like `documents.read`, `billing.write`)
* Group permissions into **roles** (like `admin`, `editor`, `viewer`)
* Attach roles or permissions directly to keys
* Check permissions during verification
## When to use this
Different customers get different feature access. Enterprise keys can do
more than free-tier keys.
Admin keys can delete resources, editor keys can modify, viewer keys can
only read.
Only keys with `beta.access` permission can use new features.
Keys can only access specific resources: `project.123.read`,
`project.456.write`.
## How it works
Create permissions that map to actions in your app: `documents.read`,
`documents.write`, `users.delete`.
Group permissions into roles for easier management. An `editor` role might
include `documents.read` and `documents.write`.
When creating or updating keys, assign roles or direct permissions.
Pass a permission query when verifying. Unkey checks if the key has the
required permissions.
## Quick example
```typescript theme={"theme":"kanagawa-wave"}
// When verifying, check for required permission
try {
const { meta, data } = await unkey.keys.verifyKey({
key: "sk_...",
permissions: "documents.write", // Key must have this permission
});
if (!data.valid) {
// Either invalid key OR missing permission
console.log(data.code); // "VALID", "FORBIDDEN", "INSUFFICIENT_PERMISSIONS", etc.
}
} catch (err) {
console.error(err);
return Response.json({ error: "Internal error" }, { status: 500 });
}
```
## Permissions vs Roles
| Concept | What it is | Example |
| -------------- | ---------------------- | ----------------------------------------------------------- |
| **Permission** | A specific action | `documents.read`, `billing.manage` |
| **Role** | A group of permissions | `admin` = all permissions, `viewer` = read-only permissions |
You can attach **either** (or both) directly to keys:
* Attach roles when you want predefined access levels
* Attach permissions directly for fine-grained control
## Next steps
Set up your authorization structure in the dashboard
Check permissions when verifying keys
See a complete implementation