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 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

Create roles & permissions

Set up your authorization structure in the dashboard

Verify permissions

Check permissions when verifying keys

Full example

See a complete implementation

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Authorization Overview

When to use this

Multi-tenant SaaS

Team permissions

Feature flags

Resource scoping

How it works

Quick example

Permissions vs Roles

Next steps

Create roles & permissions

Verify permissions

Full example

​When to use this

Multi-tenant SaaS

Team permissions

Feature flags

Resource scoping

​How it works

​Quick example

​Permissions vs Roles

​Next steps

Create roles & permissions

Verify permissions

Full example

When to use this

How it works

Quick example

Permissions vs Roles

Next steps