How groups organize wallets, actions, and usage keys in Lit Chipotle.
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:
Wallets (PKPs) — which wallets can be used
IPFS Actions — which lit-actions can be executed
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.
┌─────────────────────────┐ │ Group 1 │ │ │ Usage Key A ─────────►│ Wallet X Action CID │ (execute_in: [1]) │ Wallet Y Action CID │ │ │ └─────────────────────────┘ ┌─────────────────────────┐ │ Group 2 │ │ │ Usage Key B ─────────►│ Wallet Z Action CID │ (execute_in: [1,2]) │ │ │ │ └─────────────────────────┘
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
Resource
Relationship to Group
Wallet (PKP)
Added via add_pkp_to_group. A wallet can belong to multiple groups.
IPFS Action
Added via add_action_to_group (raw CID, server hashes it). An action can belong to multiple groups.
Usage API Key
Granted access at creation via permission arrays (e.g., execute_in_groups: [1, 2]). Only execute_in_groups supports [0] as a wildcard; management permissions require explicit group IDs.
Account Key
Administers all groups; use a usage key for action execution.
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:
Create an empty group with both membership arrays empty.
Have the account owner update the usage key with the returned group ID in the required management scopes.
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
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).
Configure — Add wallets (add_pkp_to_group) and actions (add_action_to_group).
Grant access — Create or update usage keys with the group ID in their permission arrays.
Update — POST /core/v1/update_group to change name, description, or permission lists.
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:
Authentication Model — every scope, the permission matrix, and how ChainSecured mode emerges from configuration
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Documentation","colors":{"primary":"#0D9373","light":"#F97316","dark":"#EA580C"},"logo":{"light":"https://mintcdn.com/litprotocol/QETV3ZoD4rHDsUls/logo/light.svg?fit=max\u0026auto=format\u0026n=QETV3ZoD4rHDsUls\u0026q=85\u0026s=5bf9ff54e3d9d64f6068e4d5aac6035d","dark":"https://mintcdn.com/litprotocol/QETV3ZoD4rHDsUls/logo/dark.svg?fit=max\u0026auto=format\u0026n=QETV3ZoD4rHDsUls\u0026q=85\u0026s=7ed0fceb7a8b48e80cd7e3c2bb75b9ed"},"favicon":"https://mintcdn.com/litprotocol/QETV3ZoD4rHDsUls/favicon.svg?fit=max\u0026auto=format\u0026n=QETV3ZoD4rHDsUls\u0026q=85\u0026s=b3101ee95b738bfffbefda6094e7c657","navbar":{"links":[]},"footer":{"socials":{"x":"https://twitter.com/litprotocol","discord":"https://litgateway.com/discord","github":"https://github.com/LIT-Protocol/chipotle"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"litprotocol","hasAudioNarration":false,"actualSubdomain":"litprotocol","customDomains":["developer.litprotocol.com"],"gitSource":{"type":"github","owner":"lit-protocol","repo":"chipotle","deployBranch":"main","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":true,"edits":false,"issues":false},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af7add7a50788a57d5b14a9","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"Building on Lit Protocol","count":41},{"language":"default","tag":"Architecture","count":14},{"language":"default","tag":"Lit Actions","count":11},{"language":"default","tag":"Security \u0026 Verification","count":8},{"language":"default","tag":"Management","count":8},{"language":"default","tag":"Lit Agent Keychain","count":6},{"language":"default","tag":"Guides","count":5},{"language":"default","tag":"Lit Triggers","count":3},{"language":"default","tag":"Migration","count":2},{"language":"default","tag":"Actions Reference","count":1}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"architecture/groups","slug":"/architecture/groups","pageMetadata":{"title":"Groups","description":"How groups organize wallets, actions, and usage keys in Lit Chipotle.","href":"/architecture/groups"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How groups organize wallets, actions, and usage keys in Lit Chipotle.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Mermaid,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Mermaid)_missingMdxReference(`Mermaid`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`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 `,_jsx(_components.code,{children:`QmABC`}),` and the PKP `,_jsx(_components.code,{children:`pkp_001`}),`. When K sends the code whose CID is `,_jsx(_components.code,{children:`QmABC`}),`, the action runs, and it may sign with `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(_components.p,{children:`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:`}),`\n`,_jsx(Mermaid,{chart:`%%{init: {\"flowchart\": {\"useMaxWidth\": false}}}%%\nflowchart TD\n A[\"Request: usage key,\u003cbr/>code, js_params\"] --> C([\"Can this key run\u003cbr/>this code's CID?\"])\n C -->|no| X[\"Refused with 403\"]\n C -->|yes| D[\"Run main(js_params)\u003cbr/>in the TEE\"]\n D -->|asks for a PKP| F([\"Is the PKP in a group\u003cbr/>with this CID that\u003cbr/>the key can use?\"])\n F -->|no| Y[\"The PKP call fails\"]\n F -->|yes| G[\"Derive the PKP key\u003cbr/>in the TEE\"]\n G --> R[\"Response: whatever\u003cbr/>main returned\"]\n D -->|no PKP| R`}),`\n`,_jsxs(_components.p,{children:[`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 (`,_jsx(_components.code,{children:`execute_in_groups: [0]`}),`) passes the first check for any code, but it still needs a group to use a PKP.`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-is-a-group`,children:`What is a Group?`}),`\n`,_jsxs(_components.p,{children:[`A `,_jsx(_components.strong,{children:`group`}),` is the core organizing unit in Lit Chipotle. It binds together three things:`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Wallets (PKPs)`}),` — which wallets can be used`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`IPFS Actions`}),` — which lit-actions can be executed`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(CodeBlock,{numberOfLines:`16`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`16`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` ┌─────────────────────────┐`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ Group 1 │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` Usage Key A ─────────►│ Wallet X Action CID │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` (execute_in: [1]) │ Wallet Y Action CID │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` └─────────────────────────┘`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` ┌─────────────────────────┐`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ Group 2 │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` Usage Key B ─────────►│ Wallet Z Action CID │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` (execute_in: [1,2]) │ │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` │ │`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` └─────────────────────────┘`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`2`,id:`why-groups-exist`,children:`Why Groups Exist`}),`\n`,_jsx(_components.p,{children:`Without groups, every usage key would have access to every wallet and every action in your account. Groups let you:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Isolate environments`}),` — separate staging actions from production actions.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Rotate access safely`}),` — revoke a usage key without affecting other keys or groups.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`how-groups-connect-to-everything`,children:`How Groups Connect to Everything`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Resource`}),_jsx(_components.th,{children:`Relationship to Group`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Wallet (PKP)`})}),_jsxs(_components.td,{children:[`Added via `,_jsx(_components.code,{children:`add_pkp_to_group`}),`. A wallet can belong to multiple groups.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`IPFS Action`})}),_jsxs(_components.td,{children:[`Added via `,_jsx(_components.code,{children:`add_action_to_group`}),` (raw CID, server hashes it). An action can belong to multiple groups.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Usage API Key`})}),_jsxs(_components.td,{children:[`Granted access at creation via permission arrays (e.g., `,_jsx(_components.code,{children:`execute_in_groups: [1, 2]`}),`). Only `,_jsx(_components.code,{children:`execute_in_groups`}),` supports `,_jsx(_components.code,{children:`[0]`}),` as a wildcard; management permissions require explicit group IDs.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Account Key`})}),_jsx(_components.td,{children:`Administers all groups; use a usage key for action execution.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`common-patterns`,children:`Common Patterns`}),`\n`,_jsx(Heading,{level:`3`,id:`one-group-per-dapp`,children:`One group per dApp`}),`\n`,_jsx(CodeBlock,{numberOfLines:`3`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`Group \"Price Oracle\" → wallet-A, action-QmPriceOracle`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`Group \"NFT Minter\" → wallet-B, action-QmMintNFT`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`Give each dApp its own usage key scoped to its group. If the price-oracle key leaks, the minter is unaffected.`}),`\n`,_jsx(Heading,{level:`3`,id:`all-access-key-for-development`,children:`All-access key for development`}),`\n`,_jsxs(_components.p,{children:[`Create a usage key with `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[`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 `,_jsx(_components.strong,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[`For example, `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(_components.p,{children:`Use a scoped key when you want to restrict which code can execute. Expired and revoked keys do not gain access through wildcard permissions.`}),`\n`,_jsx(Heading,{level:`3`,id:`delegating-group-management`,children:`Delegating group management`}),`\n`,_jsxs(_components.p,{children:[`The group-management permissions on a usage key (`,_jsx(_components.code,{children:`add_pkp_to_groups`}),`, `,_jsx(_components.code,{children:`remove_pkp_from_groups`}),`, `,_jsx(_components.code,{children:`manage_ipfs_ids_in_groups`}),`) are scoped by `,_jsx(_components.strong,{children:`group`}),`, not by wallet or action. Treat a key holding them as an administrator of those groups:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`add_pkp_to_groups: [g]`}),` lets the key add `,_jsx(_components.strong,{children:`any`}),` wallet in the account to group `,_jsx(_components.code,{children:`g`}),`, including wallets that were never in `,_jsx(_components.code,{children:`g`}),` and the all-wallets wildcard (zero address), which also covers wallets created later. There is no per-wallet grant on a usage key.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`manage_ipfs_ids_in_groups: [g]`}),` lets the key add any action CID to `,_jsx(_components.code,{children:`g`}),`, including the all-actions wildcard `,_jsx(_components.code,{children:`0`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Any key with `,_jsx(_components.code,{children:`execute_in_groups`}),` containing `,_jsx(_components.code,{children:`g`}),` (including a wildcard execution key) can then use those wallets with those actions, which includes signing, decryption and `,_jsx(_components.code,{children:`getPrivateKey`}),`. The one exception is the account’s own wallet, whose key is never exported (see `,_jsx(_components.a,{href:`#the-account-master-wallet`,children:`The Account Master Wallet`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`can_create_groups`}),` on its own creates `,_jsx(_components.strong,{children:`empty`}),` groups. Listing wallets or actions in `,_jsx(_components.code,{children:`add_group`}),` writes the new group’s membership, so a usage key needs the same grants on the new group that `,_jsx(_components.code,{children:`add_pkp_to_group`}),` and `,_jsx(_components.code,{children:`add_action_to_group`}),` need: the new group’s id in `,_jsx(_components.code,{children:`add_pkp_to_groups`}),` for `,_jsx(_components.code,{children:`pkp_ids_permitted`}),`, and in `,_jsx(_components.code,{children:`manage_ipfs_ids_in_groups`}),` for `,_jsx(_components.code,{children:`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.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`So add rights on `,_jsx(_components.code,{children:`g`}),` combined with execute rights in `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`execute_in_groups`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`updating-keys-with-legacy-management-grants`,children:`Updating keys with legacy management grants`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`[0]`}),` is a wildcard only in `,_jsx(_components.code,{children:`execute_in_groups`}),`. It grants no access in `,_jsx(_components.code,{children:`manage_ipfs_ids_in_groups`}),`, `,_jsx(_components.code,{children:`add_pkp_to_groups`}),`, or `,_jsx(_components.code,{children:`remove_pkp_from_groups`}),`. The Dashboard offers `,_jsx(_components.strong,{children:`All Groups`}),` only for execution and labels saved management entries of `,_jsx(_components.code,{children:`0`}),` as `,_jsx(_components.strong,{children:`no management access`}),`. Editing a key preserves saved entries until you change them.`]}),`\n`,_jsxs(_components.p,{children:[`For a key that previously created populated groups using `,_jsx(_components.code,{children:`can_create_groups`}),` and `,_jsx(_components.code,{children:`[0]`}),` management grants, use the account key to create and fill the group, or:`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsx(_components.li,{children:`Create an empty group with both membership arrays empty.`}),`\n`,_jsx(_components.li,{children:`Have the account owner update the usage key with the returned group ID in the required management scopes.`}),`\n`,_jsx(_components.li,{children:`Use that key to add the wallets and actions to the group.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The Dashboard’s `,_jsx(_components.strong,{children:`All displayed options`}),` selects the displayed group IDs for management; it does not grant access to future groups. Keep `,_jsx(_components.code,{children:`execute_in_groups: [0]`}),` only if wildcard execution is intended.`]}),`\n`,_jsx(Heading,{level:`3`,id:`the-account-master-wallet`,children:`The Account Master Wallet`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`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. `,_jsx(_components.code,{children:`Lit.Actions.Encrypt`}),` and `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`POST /core/v1/create_wallet`}),` and add it to the group. Existing keys, addresses and derivation paths are unchanged.`]}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`3`,id:`usage-key-wallets`,children:`Usage-key wallets`}),`\n`,_jsxs(_components.p,{children:[`Usage keys created through the API-mode `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`getPrivateKey`}),`.`]}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`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.`})}),`\n`,_jsx(_components.p,{children:`To keep usage credentials separate:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`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.`}),`\n`,_jsxs(_components.li,{children:[`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 `,_jsx(_components.a,{href:`#delegating-group-management`,children:`Delegating group management`}),`.`]}),`\n`,_jsx(_components.li,{children:`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.`}),`\n`]}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`3`,id:`shared-wallets-across-groups`,children:`Shared wallets across groups`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`2`,id:`group-lifecycle`,children:`Group Lifecycle`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Create`}),` — `,_jsx(_components.code,{children:`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 `,_jsx(_components.a,{href:`#delegating-group-management`,children:`Delegating group management`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Configure`}),` — Add wallets (`,_jsx(_components.code,{children:`add_pkp_to_group`}),`) and actions (`,_jsx(_components.code,{children:`add_action_to_group`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Grant access`}),` — Create or update usage keys with the group ID in their permission arrays.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Update`}),` — `,_jsx(_components.code,{children:`POST /core/v1/update_group`}),` to change name, description, or permission lists.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Delete`}),` — `,_jsx(_components.code,{children:`POST /core/v1/remove_group`}),` to remove the group. Usage keys that referenced it lose that access.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`revocation-during-a-running-action`,children:`Revocation during a running action`}),`\n`,_jsx(_components.p,{children:`Each PKP private-key request and PKP AES encrypt/decrypt operation checks wallet\npermission through the shared blockchain cache, including repeated operations in\nthe same action execution. An execution does not retain its first permission\ndecision for its entire lifetime.`}),`\n`,_jsx(_components.p,{children:`Revocation is not instantaneous. API mutation hooks and the on-chain account-event\nlistener selectively invalidate affected cache entries; the listener polls every\n10 seconds. Cached grants expire after 300 seconds without a hit; each hit\nrenews that window, but never past the calling usage key’s expiration. Cached\ndenials expire 30 seconds after insertion or update, without extension on reads.\nBoth grants and denials are invalidated by relevant events: once a grant event is\nprocessed successfully, the next lookup can observe the new permission without\nwaiting for the denial TTL. This is not instantaneous; mining, polling, RPC\nvisibility, and usage-key invalidation affect propagation.`}),`\n`,_jsx(_components.p,{children:`A usage key’s expiration emits no event, so it is enforced by the cache itself:\nwhen a grant is cached, the server reads the calling key’s expiration from chain\nand does not serve the grant from cache at or after that time, however often it is\nused. The next lookup goes back to the chain, which rejects the expired key. The\nexpiration is compared with the server’s clock, which can differ from block\ntimestamps by a few seconds. If the expiration cannot be read, the grant is not\ncached, and the read is retried after 30 seconds.`}),`\n`,_jsx(_components.p,{children:`There is no hard maximum age for a continuously used grant of a key without an\nexpiration. If the listener misses an event or invalidation is incomplete, a hot\nstale grant can remain usable indefinitely, or until the key expires if it has an\nexpiration. Denials retain their short TTL as a fallback. Once a fresh lookup is\nrequired, lookup errors stop the operation rather than falling back to an old\ngrant. Wallet-derivation caching retains its separate fixed five-minute TTL.`}),`\n`,_jsx(_components.p,{children:`An operation whose permission check started before invalidation may still finish.\nRevocation does not erase a private key already returned to action code, terminate\nthe running action, or revoke access granted through another matching group.`}),`\n`,_jsx(Heading,{level:`2`,id:`permission-flags-on-groups`,children:`Permission Flags on Groups`}),`\n`,_jsx(_components.p,{children:`When creating a group, two convenience flags control default access:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`All wallets permitted`}),` — any wallet in the account can be used via this group (no need to add individually).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`All actions permitted`}),` — any action CID matches this group, including code that has not been registered.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`These are set in the Dashboard’s group creation form or via the `,_jsx(_components.code,{children:`pkp_ids_permitted`}),` and `,_jsx(_components.code,{children:`cid_hashes_permitted`}),` arrays in the API. On-chain, these flags are `,_jsx(_components.em,{children:`not`}),` separate booleans: they are encoded using wildcard values in the arrays:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`To permit `,_jsx(_components.strong,{children:`all wallets`}),`, include the zero PKP ID in `,_jsx(_components.code,{children:`pkp_ids_permitted`}),`. PKP IDs are 20-byte wallet addresses, so this is the zero address:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`pkp_ids_permitted: [\"0x0000000000000000000000000000000000000000\"]`})}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`To permit `,_jsx(_components.strong,{children:`all actions`}),`, include `,_jsx(_components.code,{children:`0`}),` in `,_jsx(_components.code,{children:`cid_hashes_permitted`}),`. The array holds strings, so send it as `,_jsx(_components.code,{children:`\"0\"`}),`:`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`cid_hashes_permitted: [\"0\"]`})}),`\n`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Leaving these arrays empty or omitting them does `,_jsx(_components.strong,{children:`not`}),` mean “all” — it means no wallets/actions are automatically permitted by default.`]}),`\n`,_jsx(Heading,{level:`2`,id:`further-reading`,children:`Further Reading`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/management/api_direct`,children:`API Reference`}),` — Full endpoint docs for group management`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/management/api_keys`,children:`API Keys`}),` — How usage keys connect to groups`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/index`,children:`Architecture`}),` — System design overview`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/architecture/authModel`,children:`Authentication Model`}),` — every scope, the permission matrix, and how ChainSecured mode emerges from configuration`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Groups","description":"How groups organize wallets, actions, and usage keys in Lit Chipotle.","href":"/architecture/groups"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"What is a Group?","slug":"what-is-a-group","depth":2,"children":[]},{"title":"Why Groups Exist","slug":"why-groups-exist","depth":2,"children":[]},{"title":"How Groups Connect to Everything","slug":"how-groups-connect-to-everything","depth":2,"children":[]},{"title":"Common Patterns","slug":"common-patterns","depth":2,"children":[{"title":"One group per dApp","slug":"one-group-per-dapp","depth":3,"children":[]},{"title":"All-access key for development","slug":"all-access-key-for-development","depth":3,"children":[]},{"title":"Delegating group management","slug":"delegating-group-management","depth":3,"children":[]},{"title":"Updating keys with legacy management grants","slug":"updating-keys-with-legacy-management-grants","depth":3,"children":[]},{"title":"The Account Master Wallet","slug":"the-account-master-wallet","depth":3,"children":[]},{"title":"Usage-key wallets","slug":"usage-key-wallets","depth":3,"children":[]},{"title":"Shared wallets across groups","slug":"shared-wallets-across-groups","depth":3,"children":[]}]},{"title":"Group Lifecycle","slug":"group-lifecycle","depth":2,"children":[]},{"title":"Revocation during a running action","slug":"revocation-during-a-running-action","depth":2,"children":[]},{"title":"Permission Flags on Groups","slug":"permission-flags-on-groups","depth":2,"children":[]},{"title":"Further Reading","slug":"further-reading","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/litprotocol/ebcbd32a4055122d/lit-analytics.js"],"subdomain":"litprotocol","siteName":"Documentation","title":"Groups - Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-14T00:39:54.878Z","originalFileLocation":"architecture/groups.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How groups organize wallets, actions, and usage keys in Lit Chipotle.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Groups - Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"How groups organize wallets, actions, and usage keys in Lit Chipotle.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developer.litprotocol.com/architecture/groups\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://litprotocol.mintlify.site/_mintlify/api/og/v2?division=Architecture\u0026amp;title=Groups\u0026amp;description=How+groups+organize+wallets%2C+actions%2C+and+usage+keys+in+Lit+Chipotle.\u0026amp;theme=2dd36420b7ae8ee94becdf36\u0026amp;signature=5d1d94503ceee8603ec552e3811845f745b643d195c6ca4c88660d0209da802b\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Groups - Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How groups organize wallets, actions, and usage keys in Lit Chipotle.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://litprotocol.mintlify.site/_mintlify/api/og/v2?division=Architecture\u0026amp;title=Groups\u0026amp;description=How+groups+organize+wallets%2C+actions%2C+and+usage+keys+in+Lit+Chipotle.\u0026amp;theme=2dd36420b7ae8ee94becdf36\u0026amp;signature=5d1d94503ceee8603ec552e3811845f745b643d195c6ca4c88660d0209da802b\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/litprotocol/XrIhJ421GD_nEydJ/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0D9373\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developer.litprotocol.com/architecture/groups\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/architecture/groups.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developer.litprotocol.com/#organization\",\"name\":\"Documentation\",\"url\":\"https://developer.litprotocol.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/litprotocol/QETV3ZoD4rHDsUls/logo/light.svg?fit=max\u0026auto=format\u0026n=QETV3ZoD4rHDsUls\u0026q=85\u0026s=5bf9ff54e3d9d64f6068e4d5aac6035d\"}},{\"@type\":\"WebSite\",\"@id\":\"https://developer.litprotocol.com#website\",\"name\":\"Documentation\",\"url\":\"https://developer.litprotocol.com\",\"publisher\":{\"@id\":\"https://developer.litprotocol.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developer.litprotocol.com/architecture/groups#webpage\",\"url\":\"https://developer.litprotocol.com/architecture/groups\",\"name\":\"Groups\",\"description\":\"How groups organize wallets, actions, and usage keys in Lit Chipotle.\",\"dateModified\":\"2026-11-14T00:39:54.878Z\",\"isPartOf\":{\"@id\":\"https://developer.litprotocol.com#website\"},\"breadcrumb\":{\"@id\":\"https://developer.litprotocol.com/architecture/groups#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developer.litprotocol.com/architecture/groups#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Architecture\",\"item\":\"https://developer.litprotocol.com/architecture\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Groups\",\"item\":\"https://developer.litprotocol.com/architecture/groups\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://developer.litprotocol.com/architecture/groups#article\",\"headline\":\"Groups\",\"name\":\"Groups\",\"description\":\"How groups organize wallets, actions, and usage keys in Lit Chipotle.\",\"url\":\"https://developer.litprotocol.com/architecture/groups\",\"mainEntityOfPage\":{\"@id\":\"https://developer.litprotocol.com/architecture/groups#webpage\"},\"dateModified\":\"2026-11-14T00:39:54.878Z\",\"publisher\":{\"@id\":\"https://developer.litprotocol.com/#organization\"},\"isPartOf\":{\"@id\":\"https://developer.litprotocol.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Documentation\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Documentation\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/architecture/groups.md","siteName":"Documentation","nav":{"global":null,"tabs":[{"tab":"Building on Lit Protocol","pages":[{"title":"Lit Protocol","href":""},{"title":"Quick Start","href":"/quickstart"},{"title":"Glossary","href":"/glossary"},{"group":"Guides","pages":[{"title":"Guides","href":"/guides/index"}]},{"group":"Management","pages":[{"title":"API Keys","href":"/management/api_keys"},{"title":"Dashboard","href":"/management/dashboard"},{"title":"API","href":"/management/api_direct"},{"title":"API Mode vs ChainSecured Mode","href":"/management/account_modes"},{"title":"Pricing","href":"/management/pricing"},{"title":"Crypto Payments","href":"/management/crypto"},{"title":"LITKEY","href":"/management/litkey"},{"title":"Errors","href":"/management/errors"}]},{"group":"Lit Actions","pages":[{"title":"Overview","href":"/lit-actions/index"},{"title":"Module Imports","href":"/lit-actions/imports"},{"title":"WebAssembly (WASM)","href":"/lit-actions/wasm"},{"title":"Examples","href":"/lit-actions/examples"},{"title":"Patterns","href":"/lit-actions/patterns"},{"title":"Derived Actions","href":"/lit-actions/derived-actions"},{"title":"Signed Data in Untrusted Storage","href":"/lit-actions/signed-storage"},{"title":"Secrets","href":"/lit-actions/secrets"},{"title":"Limits","href":"/lit-actions/limits"},{"group":"Migration","pages":[{"title":null,"href":"/lit-actions/migration/changes"},{"title":"Encryption \u0026 Decryption","href":"/lit-actions/migration/encryption"}]}]},{"group":"Lit Triggers","pages":[{"title":"Overview","href":"/lit-triggers/index"},{"title":"Creating Triggers","href":"/lit-triggers/triggers"},{"title":"Examples","href":"/lit-triggers/examples"}]},{"group":"Architecture","pages":[{"title":"Overview","href":"/architecture/index"},{"title":"Chain Secured","href":"/architecture/chain-secured"},{"title":"Authentication Model","description":"How accounts, API keys, PKPs, groups, and the TEE root key compose into a programmable KMS — and how API mode vs ChainSecured mode emerges from configuration.","href":"/architecture/authModel"},{"title":"Groups","href":"/architecture/groups"},{"title":"Entity Relationships","description":"Entity relationships, on-chain vs TEE boundaries, and how API mode vs ChainSecured mode emerges from configuration.","href":"/architecture/diagram"},{"group":"Security \u0026 Verification","pages":[{"title":"Security \u0026 Verification","href":"/architecture/verification/index"},{"title":"What Is Attestation?","href":"/architecture/verification/attestation"},{"title":"Verify in 30 Seconds","href":"/architecture/verification/quick-verify"},{"title":"On-Chain KMS","href":"/architecture/verification/onchain-kms"},{"title":"Upgrade Governance","href":"/architecture/verification/upgrade-governance"},{"title":"Chain of Trust Reference","href":"/architecture/verification/chain-of-trust"},{"title":"Full Verification Guide","href":"/architecture/verification/full-verification"},{"title":"Bug Bounty Program","href":"/architecture/verification/bug-bounty"}]},{"title":"Self-Hosting","href":"/architecture/self-hosting"}]},{"group":"Actions Reference","pages":[{"title":"Lit Actions SDK","href":"/lit-actions/chipotle"}]}]},{"tab":"Lit Agent Keychain","pages":[{"title":"Lit Agent Keychain","href":"/keychain"}]}]},"basePath":"","title":"Groups - Documentation","buildId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","deploymentId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","dynamics":[],"chunks":[]}