Resource permissions combine a URN pattern with an action. The resource
path identifies the resource type and scope. The action identifies the
operation.
Read Unkey Resource Names for
URN format and pattern rules. Use the
resource permission catalog
to find each canonical resource path and its supported actions.
A permission has two parts separated by #.
This permission grants read access to one key:
Standard grants use an exact canonical resource path. Use * only in ID
segments when a grant covers multiple resource instances:
The path makes this a key permission. The same read action on an environment
path grants environment access instead.
Permission matching
A permission grants access when both of these conditions are true:
- The permission resource pattern matches the request resource URN.
- The permission action matches the request action.
Match resource patterns with the URN rules. Match actions with exact text. The
only action wildcard is the global admin permission
unkey:v1:{workspace_id}:**#*.
An exact app path does not grant access to its descendants:
Use a trailing /** only for an intentional subtree grant. It covers the base
resource and every current or future descendant for the same action:
This permission authorizes write on the app, its environments, deployments,
and other descendants.
A /** grant also covers descendant resource types added to the catalog
later. Use an exact canonical path unless future descendants belong in the
grant.
Action rules
Canonical actions use generic operation names. The resource path identifies the
target resource type.
decrypt, verify, and limit are special actions. Use them only on catalog
resources that support them.
Create and update rules
Use write for create and update operations. Do not define separate create or
update actions.
Use the concrete resource ID when the resource exists:
Use * in the target resource ID position when the resource does not exist:
The wildcard applies only to that path segment. It does not grant access to
other keyspaces or projects.
Resource-owned operations
Check an operation against the resource that owns the resulting state change.
Do not add an action for each API endpoint.
Log rules
Logs are first-class resources. Each log resource supports read. Its path
identifies the log source.
Read access to a parent resource does not grant read access to its logs. Grant
the exact log resource path or use an intentional subtree grant.
Find all log resource paths in the
resource permission catalog.
Legacy permission tuples
Root key permissions predate this format. A legacy grant is a dotted
{resource_type}.{resource_id}.{action} tuple rather than a URN, and the two
formats are evaluated separately: a tuple is matched as literal text, so a *
stored inside one does not expand the way a URN wildcard does, and a
workspace-wide URN grant never satisfies a tuple requirement.
Routes that predate the canonical catalog therefore accept either format, and
the tuple arms may be removed once the root key rewrite has run and no stored
permission is still in tuple form. Every site that will then need editing
carries a comment naming legacy tuples, so one repo-wide search finds them all:
One legacy string has no canonical form and is deliberately not rewritten: the
catch-all * that some root keys hold in place of a tuple. Its nearest
canonical equivalent would cover portal session minting, which the catch-all
does not grant today.
Global admin
This permission grants every action on every resource in a workspace:
Use this permission only for workspace administrators.
Related pages
Use these pages for URN rules, the resource catalog, and WorkOS role expansion.
