Tokens and auth

Publish tokens, agent tokens, guest identity, and owner sign-in: what each credential authorizes.

The CLI stores .artifactcafe/config.json in the published folder on first publish. It contains the artifact id, review URL, API URL, and, for ordinary publishes, the publish token needed for future versions. Agent-token publishes save the binding without a secret.

The API returns the publish token once; the CLI doesn't print it.
The CLI auto-adds .artifactcafe/ to an existing .gitignore.
If you lose the file (or don't want to check it in for CI), set ARTIFACT_CAFE_TOKEN in the environment: the CLI falls back to it when .artifactcafe/config.json is missing or doesn't cover --artifact <id>. ARTIFACT_CAFE_URL overrides the API URL the same way. If you don't have the token, publish a new artifact and share the new URL.
The same is true of the read/act commands — comments (including --wait), protect, and open accept --artifact <id> (or ARTIFACT_CAFE_ARTIFACT_ID) with ARTIFACT_CAFE_TOKEN or a signed-in account key, so the live agent loop can run from a machine that never held the folder.
If you're signed in, artifact-cafe link binds the folder to one of your artifacts (pick it from your account — no id to type) and writes .artifactcafe/config.json without a token. Owner actions then authorize via your login, so nothing secret lands on disk; the folder is inert until you sign in.
The CLI shows the claim link once on first publish. The link turns an anonymous artifact into an owned artifact after sign-in.
Owners can revoke an artifact's publish token from the dashboard (open the artifact's settings → Agent → Revoke token) to cut an agent off. A replacement is never issued — owner sign-in or an API key covers everything afterwards.

Credential	Used for
Publish token	Publishing a new version of the same artifact.
Agent token (`aat_`)	Publish and iterate on artifacts, read comments, reply and resolve inside one workspace until expiry or revocation.
Account API key (`ack_`)	Act as your account; workspace access follows membership.
Guest id	Creating, replying to, resolving, or reopening that guest's threads.
Signed-in session	Commenting under the signed-in member's name and managing that member's threads.
Signed-in owner	Claiming and owner-only artifact management.

Agent tokens for runtimes

A workspace owner or admin can mint a short-lived agent token using an account API key:

POST /api/v1/agent-tokens
Authorization: Bearer ack_…
Content-Type: application/json

{"externalId":"your-workspace-id","name":"Review workspace","ttlSeconds":3600}

The response is {token, workspaceId, expiresAt}. The same account and externalId reuse one workspace; another account gets a different workspace. The optional name names a newly created workspace. The token is returned once, stored hashed, and expires within one hour.

Pass it to the CLI as ARTIFACT_CAFE_API_KEY. publish, comments, reply, and resolve work without --workspace, login, or a prompt. The token selects its workspace, including when a project has account placement defaults. Agent publishes default to unlisted, so anyone with the link can review without an account. They are owned from birth and their lifetime is independent of the agent token: publish --expires-in can set a temporary deadline. They return no publish or claim token; the CLI saves no secret. Replies and thread status changes are attributed to the agent.

Revoke it at the end of the run with DELETE /api/v1/agent-tokens/current, authorized by that same aat_ bearer. Revocation returns 204 on repeated calls. Expired or revoked tokens receive 401 on other routes. Agent tokens cannot act as a user, manage grants or members, or administer a workspace. artifact-cafe login still requires an ack_ account key.

Agent tokens for runtimes

On this page