Tokens

Use a workspace API token for integrations and agent work. Set it as the server-side STACKMACHINE_API_TOKEN and pass its value to the SDK constructor. A workspace in StackMachine is a namespace in GraphQL. The token belongs to one specific workspace; use that workspace’s name as the deployment owner. Create and revoke these tokens from the workspace’s API Keys page, or follow Agent authentication to sign in and choose a workspace through GraphQL.

Personal user access tokens

A personal token grants the user’s permissions across their account and workspaces. Login claim redemption returns this credential; save it separately as STACKMACHINE_USER_ACCESS_TOKEN. Use it for user-level operations such as listing workspaces and creating workspace API tokens. For ongoing integrations, prefer the narrower workspace token.

The SDK accepts a personal user token as well, when you need that access:

user-token.mjs

import StackMachine from "stackmachine";
 
const token = process.env.STACKMACHINE_USER_ACCESS_TOKEN;
if (!token) throw new Error("STACKMACHINE_USER_ACCESS_TOKEN is required");
 
const client = new StackMachine(token, { apiUrl: "https://api.stackmachine.dev/graphql" });

The SDK does not read environment variables automatically. Both token types use Authorization: Bearer <token> for direct GraphQL requests and must be used against the API environment that issued them. Verify personal tokens with viewer; verify workspace tokens with an authorized workspace operation.

Revoke personal tokens from the dashboard’s Access Tokens page. Revoking a user token does not revoke a separately created workspace API token. Store credentials in a private secret manager or an ignored file with owner-only permissions, and keep them out of browser bundles, source control, chat, and logs.