API keys and permissions
An admin API key belongs to a workspace owner. Its grant combines permissions, projects and modes. All three must permit an operation. It is not a customer access token, provider API key or subscription relay key.
Choose access
| Permission | Access |
|---|---|
full | Read and write all supported resource kinds, subject to project/mode reach. |
read | Read all supported resource kinds, subject to project/mode reach. |
<resource>:read | Read one kind, such as products:read. |
<resource>:write | Write and read one kind, such as customers:write. |
Resource kinds are projects, products, accounts, customers, logs, backups, secrets-integrations, subscription-sign-ins, starred-items and api-keys. Logs have read access only. The schema exports AdminApiKeyGrant.RESOURCE_KINDS; modem-cli api-keys permissions prints the current catalog.
Selected projects restrict a key to those IDs. All projects includes future projects. Workspace resources—keys, 1Password integrations, subscription sign-ins/relays and starred items—require All projects in both Live and Sandbox. Workspace backup operations have the same reach requirement. A project creation request also needs All projects and permission for its requested mode.
Write permission implies read for that resource. A grant containing project-scoped permissions also permits listing the projects it reaches. These rules do not let an API key widen itself.
Inspect a key
const current = await admin.apiKeys.retrieveCurrent();
console.log(current.id, current.expiresAt);
const page = await admin.apiKeys.list({ limit: 20 });
console.log(page.data);retrieveCurrent() describes the authenticating key and its owner without exposing the secret. Listing other keys needs api-keys:read and workspace reach. Follow list pagination with startingAfter and the returned list information.
A denied request returns a typed error. When the denial concerns permission, requiredPermission says what the endpoint requires. Project or mode restrictions can still reject a key with that resource permission.
Browser approval
Keys cannot create or broaden other keys. Create/edit/other-key rotation requires the owner’s signed-in browser session, including when an existing key has full access. Use the API keys screen or:
modem-cli auth login --web
modem-cli api-keys create --name ci -p products:write --liveThe approval page shows the signed-in owner, requested access, projects, modes and expiry. Customize changes the grant before approval. The CLI uses a loopback callback with PKCE and a random state value; it exchanges the one-time code for the approved key. No key secret is carried in the callback URL.
For a custom native admin application, the SDK exports startApiKeyAuthorization and exchangeApiKeyAuthorizationCode. The caller must run the callback listener, retain the verifier and state, validate the returned state and complete the exchange. The CLI login flow is the maintained ready-to-use implementation.
Rotate a secret
const rotated = await admin.apiKeys.rotateCurrent({
previousSecretExpiresIn: '1h',
});
await persistAdminSecret(rotated.secret);Rotation preserves key identity and access. The previous secret expires immediately unless a grace duration is requested. Treat the returned secret as a secret and persist it before losing the response.
A client configured with a literal key string adopts the new secret. A client configured with a key provider continues calling that provider: update the backing secret store yourself. Rotation does not broaden permissions or renew expiry. Browser approval through modem-cli auth refresh obtains a replacement grant when access or lifetime must change.
Revoke
await admin.apiKeys.revoke(otherKeyId); // api-keys:write
await admin.apiKeys.revokeCurrent(); // the authenticating keyAfter revocation, later calls using that key fail. Self inspection, self rotation and self revocation use the key itself; a browser session is not a substitute for those endpoints. Other-key management and workspace access are listed in the REST permission matrix.