Authorization Overview

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#

Multi-tenant SaaS

Different customers get different feature access. Enterprise keys can do more than free-tier keys.

Team permissions

Admin keys can delete resources, editor keys can modify, viewer keys can only read.

Feature flags

Only keys with beta.access permission can use new features.

Resource scoping

Keys can only access specific resources: project.123.read, project.456.write.

How it works#

Define permissions

Create permissions that map to actions in your app: documents.read, documents.write, users.delete.

Create roles (optional)

Group permissions into roles for easier management. An editor role might include documents.read and documents.write.

Attach to keys

When creating or updating keys, assign roles or direct permissions.

Check during verification

Pass a permission query when verifying. Unkey checks if the key has the required permissions.

Quick example#

// When verifying, check for required permissiontry {  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#

Create roles & permissions

Set up your authorization structure in the dashboard

Verify permissions

Check permissions when verifying keys

Full example

See a complete implementation