Each way you connect uses its own credential, and credentials don’t work across purposes: a CI token can’t sign in to the dashboard or connect an agent.
| Credential | Use it for | How you get it | Lifetime |
|---|---|---|---|
| OpenTofu login | Running tofu on your own machine |
tofu login stackship.run |
90 days |
| Workspace token | CI pipelines and other non-interactive OpenTofu use | Workspace CLI access page | 1–365 days, you choose |
| OAuth access token | AI agents and the REST API | Your MCP or OAuth client | 1 hour, renewable up to 30 days |
Create a workspace token
Requires the owner or admin role.
-
Open Workspaces, select the workspace, and open CLI access.
-
Choose a Purpose:
Purpose Allows Remote plan and apply Read the workspace and its state, start runs, approve runs, and read policy results. Use this for CI. State migration Read, lock, and write the workspace’s state. Use this once, when migrating state. -
Choose when it Expires after: 1, 7, 30, 90, or 365 days.
-
Select Create token.
-
Copy the token and store it in your CI system’s secret store. StackShip shows it only once.
-
Select I saved this token to clear it from the page.
A token works only for the workspace you created it in, and never has more access than you do.
Each visit to CLI access creates its token under a new service account
with a generated name, such as networking-opentofu-3f9a1c. To choose the
name, open Service account before you select Create token.
Service-account names must be unique in your organization.
Use a workspace token
Expose the token to OpenTofu as TF_TOKEN_stackship_run:
export TF_TOKEN_stackship_run='<workspace-token>'
tofu init
tofu planIn GitHub Actions, store the token as a repository secret and set it as an
environment variable on the step that runs tofu.
Revoke access
| Credential | How to revoke |
|---|---|
| OpenTofu login | tofu logout stackship.run removes only the local copy. The login outlives your browser session and keeps working until it expires (90 days), unless you leave the organization, your account is blocked, or you’re deactivated through SCIM. |
| Workspace token | The dashboard can’t list or revoke tokens yet. Choose short expiries; if a token is exposed, contact support@stackship.run. See Revoke a workspace token. |
| OAuth access token | Disconnect the agent in its client. See Disconnect an agent. |
Removing a member immediately cuts off their OpenTofu login and agents from the organization.
Revoke a workspace token
The REST API can revoke a token:
DELETE /v1/service-accounts/{service_account_id}/tokens/{token_id}It requires the owner or admin role and an Idempotency-Key header, and
returns 204 once the token stops working. OAuth access tokens get
403 MCP_OPERATION_NOT_SUPPORTED. The dashboard doesn’t show token IDs yet, so
contact support to revoke an exposed token. The audit log
records service_account.token_created and service_account.token_revoked.
Keep tokens safe
- Store tokens in a secret manager or your CI system’s secrets, never in source control.
- Don’t put tokens in URLs, logs, or chat messages.
- Use the narrowest purpose and shortest expiry that works.
- Treat downloaded state files as sensitive. They can contain secrets.