API authentication

Tiden has three credential types that are easy to confuse. They serve different purposes.

Web sessions

Web sessions are created by login. The browser receives a short-lived JWT access token and a refresh token cookie. Web sessions can call the full web API surface for the signed-in user.

Use web sessions for interactive app usage, not for scripts or CI.

API tokens

API tokens are long-lived bearer tokens for automation. They start with tfy_ and are shown once when created.

Use API tokens for:

• CLI.
• CI release creation.
• Source map upload.
• MCP server.
• Custom API clients.

Send the token as:

Authorization: Bearer <token>

API tokens can call the api.public.v1 surface only. They cannot manage other API tokens, organization members, billing, credentials, or other web-only admin operations.

Account tokens and product tokens

Every API token is one of two kinds.

An account token is created in Settings > API tokens. It acts as you: it reaches every product you can access, with your rights, and it always has full access to the api.public.v1 surface. tiden setup and tiden auth login create account tokens. When you leave, your account tokens lose that access with you.

A product token is created in Product settings > API tokens. It belongs to the product, so it keeps working when the person who created it leaves. Use product tokens for CI and for integrations that work with one product.

Product tokens

A product token is limited to its product on every public API call. With full access, a call that names another product, or an entity in another product, returns 403 with this API token is limited to product <id>. A publish-only token gets its own message, described under Access. Listing workspaces and products returns only the token's own workspace and product. A product token cannot create products or start agent runs.

Workspace owners and admins create and revoke product tokens. Every member of the product sees the list, with the access level and who created each token. The dialog that shows a new token also shows the product id: pass both to CI, as TIDEN_API_TOKEN and TIDEN_PRODUCT_ID.

Tokens created as publish-only account tokens before product tokens existed are now product tokens, under Product settings > API tokens of their product. The token value did not change, so CI secrets that hold one keep working.

Access

When you create a product token, Access sets what it can do:

• Full access to this product (the default): the whole api.public.v1 surface, for this product only. Use it for release announcements, source map upload, and tiden test ingest in CI.
• Publish test runs only: test runs for this product. Use it for CI jobs that only report test results.

A publish-only token can create a test run, read it, report results, complete or abort it, and upload run attachments, all on its own product. Every other API call, and every call for another product, returns 403 with this API token can only publish test runs for product <id>. The token cannot change or delete specs, branches, or spec links. A run it completes still updates the test cases, the living test docs, on the Tiden branch the run resolves to, which can be main. tiden test ingest and the tiden intent commands need full access.

Only intent branches

A publish-only product token can also have Only intent branches set. A test run from such a token counts only when it belongs to an intent branch: an open Tiden branch that has an intent session. Its results then count for that intent branch and its intent session, and the run updates test cases on that intent branch only. They never count toward the Quality Gate of main or of a release.

Tiden accepts a run from such a token for main, for a branch without an intent session, for a closed branch, or with no branch, and records its results. They count for nothing: no branch, no main, no release Quality Gate, and no test case update. The CI step stays green.

Tiden refuses a run that names the intent session of another branch. It also refuses such a token when it reports results to, completes, or aborts a run that was not created by a token with Only intent branches. Both calls return 403 with this API token can only publish runs to intent branches and the reason.

Use this option for workflows that run code from a pull request while it can read your repository secrets, such as a GitHub merge queue run. If that token leaks, it can add results and update test cases on an intent branch, but it cannot change what main or a release reports.

Use a publish-only token

Pass a publish-only token through the TIDEN_API_TOKEN environment variable. tiden run exec, tiden run report, tiden run complete, and the JavaScript, PHPUnit, and Swift reporters read it. With the token in the environment, the CLI sends its requests without looking up the workspace or repository first.

Do not store a publish-only token with tiden setup, tiden auth login, or tiden config set apiToken. With a stored login the CLI looks up the workspace and repository, and a publish-only token cannot make those calls. A product token with full access can make them, so you can store it like an account token. With a stored token, the CLI reports a 403 differently; see Troubleshooting.

For a GitHub setup with a token per workflow, see CI tokens.

DSN keys

DSN keys are product-scoped public ingest credentials for error tracking. They are embedded in runtime applications and can only send events to the product ingest endpoint.

A DSN key is not an API token. It cannot call the REST API.

Choosing the right credential

Job	Credential
Use the web app	Web session
Run tiden locally	Account token created by tiden setup
Report test runs from CI	Product token with Publish test runs only
Report test runs from a merge queue	Product token with Publish test runs only and Only intent branches
Create releases from CI	Product token with Full access to this product
Upload source maps from CI	Product token with Full access to this product
Send runtime exceptions	DSN key
Manage organization members	Web session
Manage billing	Web session
Manage workspace credentials	Web session

Token storage

Store API tokens in:

• ~/.tiden/config.json (one entry per workspace), shared by the CLI and the MCP server.
• CI secret stores for build automation.
• Secret managers for custom services.

Rotate a token, or add another account, with tiden auth login; remove a stored token with tiden auth logout. See Set up the CLI.

Do not commit API tokens or DSNs to source control. DSNs are less privileged, but they still identify your product's ingest stream and should be treated as configuration, not public documentation.