Skip to main content
Can this action use this key? A group is how your account answers that question. Here is one concrete case. Usage key K has execute permission in group 7. Group 7 lists the action QmABC and the PKP pkp_001. When K sends the code whose CID is QmABC, the action runs, and it may sign with pkp_001. If K sends different code, the CID is different and the request is refused. If the action asks for a PKP that group 7 doesn’t list, that call fails. The group holds the actions and the PKPs. The permission to use a group lives on the usage key, as a scope that names the group. Every request checks both: Every request takes this path. A group answers “Can this action use this PKP?” A usage key’s scopes answer “Can this caller use this group?” A wildcard key (execute_in_groups: [0]) passes the first check for any code, but it still needs a group to use a PKP.

What is a Group?

A group is the core organizing unit in Lit Chipotle. It binds together three things:
  1. Wallets (PKPs) — which wallets can be used
  2. IPFS Actions — which lit-actions can be executed
  3. Usage API Keys — which keys have access (via their permission arrays). This access is stored on each key, as a permission that names the group. The group itself doesn’t keep a list of keys.
Think of a group as an access-control boundary: scoped usage keys can run actions in their permitted groups, and PKP wallet access requires a group permitting both the action and wallet. Wildcard execution keys can run arbitrary code without a group, but still need that group match to use a PKP wallet.
In this example, Key A can only use Group 1’s wallets and actions. Key B can use both groups. The account key administers all groups; use a usage key to execute actions.

Why Groups Exist

Without groups, every usage key would have access to every wallet and every action in your account. Groups let you:
  • Scope a key to a single dApp — give your price-oracle service a key that can only execute the price-oracle action using a specific wallet.
  • Isolate environments — separate staging actions from production actions.
  • Rotate access safely — revoke a usage key without affecting other keys or groups.

How Groups Connect to Everything

Common Patterns

One group per dApp

Give each dApp its own usage key scoped to its group. If the price-oracle key leaks, the minter is unaffected.

All-access key for development

Create a usage key with execute_in_groups: [0] (wildcard). This key can run arbitrary action code, including code pasted into the Dashboard Action Runner, without registering a CID or creating a group. Execution permission and PKP wallet permission are separate. If the action requests a PKP private key or uses PKP encryption/decryption, a group in the key’s own account must permit both the action CID and the requested wallet. They must match the same group. Wildcard execution skips the individual group grants on the key; it does not skip this resource check or grant access to another account’s wallets. Group membership is not proof of wallet ownership: listing a foreign wallet address can satisfy the group check, but the node separately resolves the wallet in the caller’s account and verifies the derived key’s address before releasing or using it. For example, console.log("hello") needs no group with a wildcard key. An action using wallet A requires a group containing wallet A and that action’s CID (or the group’s all-actions wildcard). Changing the code changes its CID, so update the permitted CID or deliberately allow all actions for that group. Use a scoped key when you want to restrict which code can execute. Expired and revoked keys do not gain access through wildcard permissions.

Delegating group management

The group-management permissions on a usage key (add_pkp_to_groups, remove_pkp_from_groups, manage_ipfs_ids_in_groups) are scoped by group, not by wallet or action. Treat a key holding them as an administrator of those groups:
  • add_pkp_to_groups: [g] lets the key add any wallet in the account to group g, including wallets that were never in g and the all-wallets wildcard (zero address), which also covers wallets created later. There is no per-wallet grant on a usage key.
  • manage_ipfs_ids_in_groups: [g] lets the key add any action CID to g, including the all-actions wildcard 0.
  • Any key with execute_in_groups containing g (including a wildcard execution key) can then use those wallets with those actions, which includes signing, decryption and getPrivateKey. The one exception is the account’s own wallet, whose key is never exported (see The Account Master Wallet).
  • can_create_groups on its own creates empty groups. Listing wallets or actions in add_group writes the new group’s membership, so a usage key needs the same grants on the new group that add_pkp_to_group and add_action_to_group need: the new group’s id in add_pkp_to_groups for pkp_ids_permitted, and in manage_ipfs_ids_in_groups for cid_hashes_permitted. Otherwise the request is refused with 403. To delegate filling a group, create it first, then grant the key those permissions on its id.
So add rights on g combined with execute rights in g, whether held by one key or by two, give effective access to every wallet in the account. This is by design. If some wallets must stay out of a delegate’s reach, keep them in a separate account, or keep wallet membership changes on the account key and give delegates only execute_in_groups.

Updating keys with legacy management grants

[0] is a wildcard only in execute_in_groups. It grants no access in manage_ipfs_ids_in_groups, add_pkp_to_groups, or remove_pkp_from_groups. The Dashboard offers All Groups only for execution and labels saved management entries of 0 as no management access. Editing a key preserves saved entries until you change them. For a key that previously created populated groups using can_create_groups and [0] management grants, use the account key to create and fill the group, or:
  1. Create an empty group with both membership arrays empty.
  2. Have the account owner update the usage key with the returned group ID in the required management scopes.
  3. Use that key to add the wallets and actions to the group.
The Dashboard’s All displayed options selects the displayed group IDs for management; it does not grant access to future groups. Keep execute_in_groups: [0] only if wildcard execution is intended.

The Account Master Wallet

POST /new_account creates one wallet for the account, listed as “Account Master Wallet”. It is not an ordinary PKP: the account key is this wallet’s private key, base64-encoded, and the wallet is the account’s admin on chain. Lit Actions run only under usage keys (the account key cannot run actions), so any usage key that could export this wallet’s key would hold the account key. Lit.Actions.getPrivateKey therefore never returns the private key of the account’s admin wallet or its billing wallet, whatever the key and whatever the groups say: listing the wallet in a group, or the all-wallets entry (zero address), does not change this. The action gets an error instead. Lit.Actions.Encrypt and Lit.Actions.Decrypt still accept the wallet through groups like any other wallet, because they never reveal its key. To sign from an action, create a separate wallet with POST /core/v1/create_wallet and add it to the group. Existing keys, addresses and derivation paths are unchanged. In a ChainSecured account the admin wallet is the user’s own wallet, which the TEE cannot derive, so the rule only matters if the admin or billing wallet is one of the account’s PKPs. Converting an account to ChainSecured makes the user’s wallet the admin but keeps the original Account Master Wallet as the billing wallet. Its key is still the old account key, which still passes billing-owner checks, so the rule keeps covering it.

Usage-key wallets

Usage keys created through the API-mode add_usage_api_key endpoint also have a backing wallet, initially listed as “API Key Wallet” with description “Usage API Key Wallet”. That wallet’s private key is the usage API credential, base64-encoded. Unlike the account’s admin and billing wallets, usage-key wallets are subject to the ordinary group rules for getPrivateKey.
Granting access to a usage-key wallet can grant access to the credential itself. The all-wallets wildcard includes these wallets, including ones created later. Wallet names and descriptions are labels, not security boundaries.
To keep usage credentials separate:
  • Create dedicated application wallets and list their addresses explicitly in production groups. Keep usage-key wallets out of those groups instead of selecting all wallets.
  • Permit reviewed action CIDs that do not disclose secrets, and give callers execution access without group-management permissions. A delegate who can change wallet or action membership may broaden that access; see Delegating group management.
  • Treat disclosure of a usage-key wallet’s secret as disclosure of that usage credential. Removing group access or deleting key A does not revoke a recovered key B; revoke and replace B as well.
Usage keys generated as independent random tokens in ChainSecured mode have no backing wallet. Converting an existing account to ChainSecured preserves existing keys and wallets, so review any wallet-backed keys that remain.

Shared wallets across groups

A single wallet can belong to multiple groups. This is useful when multiple dApps need to sign with the same address but run different actions.

Group Lifecycle

  1. Create — POST /core/v1/add_group with a name and optional pre-permitted PKPs and CID hashes. A usage key can pre-permit them only with the matching grants on the new group (see Delegating group management).
  2. Configure — Add wallets (add_pkp_to_group) and actions (add_action_to_group).
  3. Grant access — Create or update usage keys with the group ID in their permission arrays.
  4. Update — POST /core/v1/update_group to change name, description, or permission lists.
  5. Delete — POST /core/v1/remove_group to remove the group. Usage keys that referenced it lose that access.

Revocation during a running action

Each PKP private-key request and PKP AES encrypt/decrypt operation checks wallet permission through the shared blockchain cache, including repeated operations in the same action execution. An execution does not retain its first permission decision for its entire lifetime. Revocation is not instantaneous. API mutation hooks and the on-chain account-event listener selectively invalidate affected cache entries; the listener polls every 10 seconds. Cached grants expire after 300 seconds without a hit; each hit renews that window, but never past the calling usage key’s expiration. Cached denials expire 30 seconds after insertion or update, without extension on reads. Both grants and denials are invalidated by relevant events: once a grant event is processed successfully, the next lookup can observe the new permission without waiting for the denial TTL. This is not instantaneous; mining, polling, RPC visibility, and usage-key invalidation affect propagation. A usage key’s expiration emits no event, so it is enforced by the cache itself: when a grant is cached, the server reads the calling key’s expiration from chain and does not serve the grant from cache at or after that time, however often it is used. The next lookup goes back to the chain, which rejects the expired key. The expiration is compared with the server’s clock, which can differ from block timestamps by a few seconds. If the expiration cannot be read, the grant is not cached, and the read is retried after 30 seconds. There is no hard maximum age for a continuously used grant of a key without an expiration. If the listener misses an event or invalidation is incomplete, a hot stale grant can remain usable indefinitely, or until the key expires if it has an expiration. Denials retain their short TTL as a fallback. Once a fresh lookup is required, lookup errors stop the operation rather than falling back to an old grant. Wallet-derivation caching retains its separate fixed five-minute TTL. An operation whose permission check started before invalidation may still finish. Revocation does not erase a private key already returned to action code, terminate the running action, or revoke access granted through another matching group.

Permission Flags on Groups

When creating a group, two convenience flags control default access:
  • All wallets permitted — any wallet in the account can be used via this group (no need to add individually).
  • All actions permitted — any action CID matches this group, including code that has not been registered.
These are set in the Dashboard’s group creation form or via the pkp_ids_permitted and cid_hashes_permitted arrays in the API. On-chain, these flags are not separate booleans: they are encoded using wildcard values in the arrays:
  • To permit all wallets, include the zero PKP ID in pkp_ids_permitted. PKP IDs are 20-byte wallet addresses, so this is the zero address:
    • pkp_ids_permitted: ["0x0000000000000000000000000000000000000000"]
  • To permit all actions, include 0 in cid_hashes_permitted. The array holds strings, so send it as "0":
    • cid_hashes_permitted: ["0"]
Leaving these arrays empty or omitting them does not mean “all” — it means no wallets/actions are automatically permitted by default.

Further Reading