Skip to Content
Getting StartedAgent authentication

Agent authentication

Agents and CLI clients can sign in without a localhost callback. The agent creates a short-lived request, gives the human an approval link and code, then receives a personal access token after the human authorizes it.

The complete machine-readable instructions are at the site’s auth.md document. This environment’s GraphQL API is https://api.stackmachine.dev/graphql.

  1. Call createLoginClaim anonymously with a recognizable clientName and optional apiKeyName. Keep the returned claimToken in the agent’s memory.
  2. Show the human the public userCode and https://dashboard.stackmachine.dev/auth/claim?code=USER_CODE.
  3. The human signs in or signs up, checks the code and requested permissions, then explicitly authorizes or denies access. Sign-in alone grants no access.
  4. After sharing the link, wait 15 seconds before the first redeemLoginClaim poll, then poll every 5 seconds while pending (or at the returned interval if longer). Keep polling without asking the human to reply once authorized; continue automatically when the token is returned. Alternatively, subscribe to loginClaimStatus and redeem once the status becomes APPROVED.
  5. Save the returned personal token privately as STACKMACHINE_USER_ACCESS_TOKEN and verify the account with viewer using that token.
  6. List the user’s workspaces and ask which one to use, even when there is only one. If none are available, ask whether to create a workspace and confirm its name before calling createNamespace. A workspace in the UI is a namespace in GraphQL.
  7. Prefer a workspace API token for integrations. With the human’s agreement, create a token for the chosen namespace with createNamespaceApiKey, or reuse an existing valid workspace token. Save it as STACKMACHINE_API_TOKEN. Do not silently fall back to a personal token if this fails.

Requests expire after ten minutes. Denied and expired requests cannot issue a token. Each request returns a token only once, even if several clients redeem concurrently. If the successful response is lost, start a new request.

Use STACKMACHINE_API_TOKEN for normal integrations. It belongs to the selected workspace (namespace). The login-issued personal token is used to verify the user and set up workspace access. See Tokens for credential scope and the personal user-token alternative.

The human can revoke workspace API tokens from the workspace’s API Keys page and personal tokens from their dashboard’s Access Tokens page. Keep the two credentials separate when saving them.

Never share the private claim token or access token with the human in chat, include it in browser URLs, or record it in public logs. The browser approval page uses only the public code and the human’s existing session.

Client setupTokens