Permissions

Golem has three related permission-management surfaces:

• API tokens authenticate automation that calls Golem APIs.
• Permission shares grant bounded card authority from one account to another.
• Cards carry authority in account and agent wallets.

For the underlying model, see Permissions and the cards reference.

API tokens

List tokens

golem api-token list

Create a token

golem api-token new

The command prints the token secret exactly once, including in structured output. Store it securely and do not put it in source control or logs.

By default, the token uses 2100-01-01T00:00:00Z as its expiry. Set an explicit RFC 3339 timestamp with a UTC offset when a shorter lifetime is appropriate:

golem api-token new --expires-at 2026-12-31T23:59:59Z

Timezone-less timestamps and relative durations such as 30d are not accepted.

Delete a token

Use the token ID shown by list or new:

golem api-token delete <token-id>

Deleting a token prevents future API authentication with that secret. It does not revoke permission cards.

Account permission shares

A permission share is owned by one account and targets another account by email address. Its lower positive and negative grants define the authority shared with the target. Golem materializes the share as a managed permission-share card.

Permission strings use class(owner) @ recipient : verb : resource. For example, this grant lets the recipient view the owner’s shop application:

Create a share

golem account permission-share new recipient@example.com deployers \
  --lower-positive 'application(owner@example.com/shop) @ recipient@example.com : view :'

The positional arguments are the target account email and the share name. A share grant’s recipient must be * or exactly the target account’s email. Repeat either grant option to add more than one pattern. Use --account <email> or --account-id <uuid> to act on another account when your credentials allow it.

List and inspect shares

List shares owned by the selected account:

golem account permission-share list

List shares received by it instead:

golem account permission-share list --received

Get a share by ID or by its owner-scoped name:

golem account permission-share get <permission-share-id>
golem account permission-share get-by-name deployers

Update or delete a share

golem account permission-share update <permission-share-id> \
  --name deployment-operators \
  --lower-positive '<permission-pattern>'
 
golem account permission-share delete <permission-share-id>

On update, omitting --name, --lower-positive, or --lower-negative preserves that existing value. Supplying a grant option replaces the corresponding list; repeat it to provide the complete replacement list. Updates and deletes use the share’s current revision and fail on a concurrent modification rather than overwriting it.

Every successful update creates a replacement managed card and revokes the previous card and all its descendants, even when only the share name changes. Deleting the share revokes its managed card and descendants without replacement.

Inspect and revoke cards

List all managed card kinds owned by the selected account:

golem card list

When any include flag is present, only the selected kinds are returned:

golem card list --include-root --include-permission-shares
golem card list --include-environment-defaults --include-agent-initials

The account scope flags --account <email> and --account-id <uuid> are mutually exclusive.

To inspect an agent’s active wallet instead, use an agent reference. This activates the agent if necessary:

golem card list --agent <agent-reference>

Agent wallet listing cannot be combined with account scope or include flags.

Inspect one card:

golem card get <card-id>

Revoke a card and all cards derived from it:

golem card revoke <card-id>

Revocation is destructive and prompts for confirmation unless the global -Y/--yes option is set. The output lists the card IDs revoked by the cascade.

Permission-share cards, environment-default cards, and system cards cannot be revoked directly. Delete or update a permission share to revoke its managed authority; change the managing environment configuration for an environment-default card.