API keys and scopes

Find the API key screen

Open Settings and select the api tab. The screen can list keys, create a key, reveal its value, and revoke a key.

Scope each key to its job

Keep separate keys for separate integrations when their scopes or spending needs differ. This makes the key list easier to audit and limits which workspace each connection can reach.

Create, reveal, and revoke

Create a key only after checking its workspace and scopes. Store the revealed value in the system that needs it, then return to the API key screen to confirm the key appears in the list. Revoke a key when the connection should no longer act for this workspace.

Choose the right credential

Machine keys are tokens bound to the current workspace for CI and shared runners. A machine key cannot switch workspaces, so create it only after selecting the workspace that the runner must operate.

Sessions are different from machine keys. The settings screen says sessions work in every workspace the user belongs to, begin in a selected workspace, and expire after 90 days of inactivity.

The MCP connection screen says connections work across a user’s workspaces. An agent can switch workspace, while the CLI can receive a workspace selection through its own supported command interface.

A key’s scopes are explicit permissions. Name a key for the integration that uses it and grant only the scopes that integration needs, rather than using one broad credential for unrelated systems.

A key also has its own spend policy. Credit limits are consent for paid work, so a caller should keep an appropriate max-credits ceiling when a discovered capability returns a quote requirement.

The API key screen lists keys for the active workspace. Verify the workspace name shown by the screen before interpreting a key row or deciding that a credential is missing.

Creating a key is an owner action because it changes who can reach workspace resources. Use the signed-in settings flow, not an API key, and keep the action tied to the workspace whose access is intended.

Revealing a key exposes a credential value. Copy it only to the secret store or runtime that needs it, because a Context page, skill, comment, or shared chat transcript is not a credential store.

Revoking a key ends that key’s access. Check the key name, prefix, workspace, and dependent integration before revocation, then confirm the revoked row or status in Settings.

A revoked session stops terminals and connections using that session in every workspace immediately. The settings screen states that this cannot be undone, so use a new login or session rather than expecting a revoked session to resume.

Connect a client carefully

For an interactive CLI login, use the documented Dreamstate login flow, which opens browser approval. For a remote machine, the documented token login is intended for SSH and remote environments.

The documented CLI environment names are DREAMSTATE_API_URL and DREAMSTATE_API_KEY. Set them only in the execution environment that owns the credential and avoid placing their values in product documents.

A credential gives access within the workspace boundary, not global product authority. It does not make the key holder an owner, and it cannot grant a scope that was not assigned to the key.

After a client authenticates, it still discovers a capability’s exact schema before execution. Authentication does not bypass tool search, fetched contracts, explicit modes, or max-credit limits.

Every mutating capability must name a mode. The server does not default mutations to live, which lets a client choose smoke_test, dry_run, or live only where the selected capability supports that mode.

Use separate keys when two integrations need different scopes, workspace boundaries, or spend policies. The resulting key list makes it possible to identify which connection should be revoked when its purpose ends.

Before a client runs work, check its workspace, scopes, and spend policy. Then search for the capability, fetch its exact contract, choose a supported mode, and inspect the result in the client or Dreamstate app.

When it goes wrong

If an integration reports an authentication failure, first verify that it is using an unrevoked key from the intended workspace. Then inspect whether the key’s scopes cover the discovered capability instead of issuing a new key without understanding the failure.

If a revealed secret is lost, do not search Context or shared messages for a copy. Revoke the exposed key and create a replacement for the same workspace and narrow scope after updating the dependent integration.

If a machine runner needs another workspace, create or use a key bound to that workspace. A machine key cannot switch, and changing an unrelated workspace key would broaden access without solving the boundary problem.

A successful setup is visible in two places: the intended key or session is listed on the API key screen, and the client can authenticate only within the workspace and scopes assigned to it.

Do not treat an access failure as a reason to reveal a secret again or grant broader access. Identify the workspace, credential type, key status, scope, and caller first, then apply the smallest credential change that addresses the verified issue.