---
title: "Agent authentication"
description: "Sign agents and CLI clients in through explicit browser consent."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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
<a href={siteUrl('/auth.md')}>the site's auth.md document</a>.
This environment's GraphQL API is <code>{getDocsApiUrl()}</code>.

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
   <code>{dashboardUrl('/auth/claim?code=USER_CODE')}</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](/getting-started/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.

Source: https://docs.stackmachine.com/getting-started/agent-authentication/index.mdx