Topolo Docs Topolo Platform
Open workspace

API keys

Choose the application, authorized resources and allowed scopes before creating or changing a key.

Choose a credential

Use an API key for an integration that needs a defined application and resource boundary. Use the normal Topolo sign-in flow when a CLI or MCP agent should act as a signed-in person. An API key does not turn an application name or organization role into permission to act.

Start with Get API key options. Its response is the caller-specific decision for the selected application and organization. General workspace or application discovery alone does not establish key eligibility.

Select resources before scopes

  1. Verify the current identity and discover the application.
  2. Read api_keys.options for that exact application and the organization carried by the credential.
  3. Check canCreate. A false result stops creation. canManageOwnKeys and canManageOtherKeys describe separate management capabilities.
  4. Choose the resource bindings. With no bindings, select only from organizationWideScopes. With bindings, select only scopes present in every selected resource's allowedScopes.
  5. Inspect the current create or update schema, validate the reviewed input, then plan the confirmed mutation. Execute only the approved selection.
topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.api_keys.options --detail --json

For example, if one selected workspace allows docs:read and docs:write and another allows only docs:read, their intersection is docs:read. This is an illustrative selection rule, not an access grant. Discover your own resources and scope names; do not reuse fixture identifiers from a worked example.

The options guide includes a captured handler response, field meanings and CLI/MCP examples. A template that needs your application or resource IDs must be completed before validation or execution.

Create, change and revoke

TaskWorked guideRead-back
Create a reviewed keyCreate API keyList API keys
Change the selected keyUpdate API keyRead the key metadata and compare the intended scopes and bindings.
Revoke a keyRevoke API keyVerify the revoked state and separately verify that its protected downstream operation is refused.

A create response can contain a credential. Local CLI and stdio MCP replace sensitive returned credentials with a protected topolo-secret:… reference. Keep that reference unchanged for the next published action. Do not extract the secret, print it, commit it or paste it into documentation. A local reference is not an API key ID and is not the raw HTTP credential value.

Deleting a local protected reference does not revoke its upstream key. Use the key's published revoke action for that operation. Revocation does not imply that already-issued downstream artifacts or an unrelated session have been removed; verify the action's own effects and recovery limits.

Resolve a refusal

An expired or missing sign-in requires normal authentication, followed by identity and options discovery again. A denied permission, inaccessible resource or unavailable scope requires a corrected authorized selection. Do not merge scopes across bindings, widen access or change organization context automatically to bypass a refusal.

Authentication explains identity and context. Auth API links the surrounding workspace and access workflows.