Skip to content
Caracal

Issue Grants and Invitations

A grant is the control-plane record that binds a principal (application or user) to a set of scopes on a resource. Without a grant, OPA policy evaluation has no basis to allow a token exchange for that principal and resource combination. Invitations bring new users into the zone as members who can hold grants.

Prerequisites

Section titled “Prerequisites”

Create a grant

Section titled “Create a grant”
Terminal window
caracal grant create \
  --app app-abc123 \
  --resource res-def456 \
  --scopes "payment:read,payment:submit"

The --app flag takes an application ID. The grant authorizes that application to request the listed scopes for the named resource. Whether the STS actually issues those scopes depends on the active policy — the grant is necessary but not sufficient.

Grant options

Section titled “Grant options”
FlagRequiredDescription
--appYesApplication ID receiving the grant
--resourceYesResource ID the grant covers
--scopesYesComma-separated scope strings the application may request
--userNoUser subject ID (for user-scoped grants rather than app-scoped)

User grant

Section titled “User grant”
Terminal window
caracal grant create \
  --app app-abc123 \
  --user user-xyz789 \
  --resource res-def456 \
  --scopes "report:read"

A user grant restricts the grant to exchanges where the subject matches --user. This is used for delegated user authority: the application acts on behalf of the specific user.

List grants

Section titled “List grants”
Terminal window
# All grants in the zone
caracal grant list


# As JSON (pipe to jq for filtering)
caracal grant list --json | jq '.[] | select(.resource_id == "res-def456")'

Inspect a grant

Section titled “Inspect a grant”
Terminal window
caracal grant get grant-ghi789

Revoke a grant

Section titled “Revoke a grant”
Terminal window
caracal grant revoke grant-ghi789

Revoking a grant does not immediately terminate active sessions or revoke already-issued mandates. The 15-minute per-call TTL on issued mandates means the effect fully propagates within that window. Future token exchanges fail at policy evaluation once the grant is gone.

Invitations

Section titled “Invitations”

Invitations add users to the zone as members. A member can receive user-scoped grants, log into the control plane, and manage their own credentials (depending on zone configuration).

Invite a user by email

Section titled “Invite a user by email”
Terminal window
caracal invitation create --email alice@example.com

The command returns an invitation token and link. Send the link to the user. Invitations expire after the configured TTL (default: 24 hours).

List pending invitations

Section titled “List pending invitations”
Terminal window
caracal invitation list

Revoke an invitation

Section titled “Revoke an invitation”
Terminal window
caracal invitation revoke inv-mno345

Checking grant effects

Section titled “Checking grant effects”

After issuing a grant, verify that an exchange would succeed by running caracal run:

Terminal window
CARACAL_APPLICATION_ID=app-abc123 \
CARACAL_SUBJECT_TOKEN=<app-token> \
caracal run --resource resource://payments -- \
  echo "grant works"

If the exchange fails, check whether:

  1. The grant exists and covers the requested scopes: caracal grant get <id>
  2. The active policy allows the exchange: caracal audit tail --limit 5 --json
  3. The policy set is active: caracal policy-set list
Section titled “What to read next”