Authorization Overview

Control what each API key can access with roles and permissions

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

1. Define permissions

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

2. Create roles (optional)

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

3. Attach to keys

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

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