Identity and access
Auth identifies the person or integration presenting a credential. The application then decides whether that caller may perform the requested operation on the selected resource. A successful sign-in does not establish a paid plan, workspace membership or every action permission.
OAuth consent scopes, application entitlement and the target application's final authorization decision are distinct. An action marked authorizationMode: runtime remains subject to the target's decision for its concrete input and credential context. Treat its denial as authoritative.
Sign in and verify
For a person using the CLI, use its built-in browser sign-in and complete the displayed approval. The first-party CLI does not require you to register a developer OAuth client.
topolo auth login
topolo auth status --json
topolo whoami --json
Confirm the returned identity and organization before reading or changing application data. Browser sign-in and CLI approval are separate steps: being signed in to a website does not prove that the CLI has received an approved credential. An expired approval code requires a new login attempt, not another use of that code.
For API-key integrations, follow API keys. For an external application implementing login, use Integrate with Auth.
Use the intended context
List the contexts available to your existing credential before selecting one:
topolo context ls --json
Use the exact discovered context key for a process pin with TOPOLO_CONTEXT; a missing pinned credential is a refusal. Context selection is a deliberate identity boundary change, not an error-recovery shortcut. Concurrent CLI or MCP sessions should use their own fixed context rather than repeatedly changing a shared active context.
Verify identity again after an authorized context change. Discover application and resource IDs within that same context; IDs, scopes and access from another organization are not interchangeable.
Follow the action contract
| Need | Current guidance |
|---|---|
| Understand application access | Get my application entitlement |
| Find the current tenant context | Get my tenant |
| Find workspaces and their caller-specific creation policy | List application workspaces |
| Inspect or revoke sessions | List sessions and Revoke a session |
| Manage linked sign-in providers | List linked providers |
| Manage passkeys | List passkeys and Begin passkey registration |
Each worked action guide describes its own identifiers, permission decision, effects, examples and read-back. A GET can include documented provisioning effects; inspect the contract before treating discovery as a storage-free operation.
Recover from expiry or denial
| Result | Next step |
|---|---|
| Missing or expired credential | Repeat normal sign-in, verify identity, then repeat discovery before the affected call. |
| Permission or resource denial | Read the reported permission and current target policy. Request an authorized access change or correct the resource selection. |
| Invalid action input | Correct the reported schema fields using the exact published action schema. |
| Interrupted mutation | Read the action's verification and recovery steps before retrying. A new login does not prove whether the first write happened. |
Keep request IDs when diagnosing a failure. Do not include tokens, passwords, API keys or passkey material in screenshots, logs or documentation. Passkey enrollment and login require the interactive browser ceremony; a local test example cannot perform it for a person.