Beta feedback from a first unattended agent integration: machine-token TTL, Idempotency-Key DX, drive bootstrap scopes

[jiashuoz]

Filed from the first real agent integration against the hosted REST API: an assistant agent was handed a console-minted machine token and wrote artifacts unattended. Three rough edges, plus what worked.

1. Machine tokens expire in 1 hour with no renewal path

A console-minted machine token is a JWT with exp - iat = 3600s. The OIDC server (auth.tokencanopy.com/oidc) advertises authorization_code and refresh_token grants but not client_credentials, and the v0 REST spec has no token-exchange endpoint. An unattended server-to-server caller cannot renew: an hour after minting, every call starts returning 401 until a human goes back to the console.

Ask: long-lived machine credentials (days/months, revocable), or a documented refresh path for machine tokens. Without one, "shared drive for agents" works for demos but not for always-on agents.

2. Artifact creation hard-requires Idempotency-Key, and fails with a bare 400

POST /v0/drives/{id}/artifacts without an Idempotency-Key header returns 400 IDEMPOTENCY_KEY_REQUIRED with nothing else in the body pointing at the missing header. Fine once you know; a first-integration stumbling block.

Ask: document the requirement prominently in the quickstart (docs/api.md), and/or name the missing header in the error message.

3. Scope model: an agent cannot bootstrap its own drive

The scopes available to machine tokens include drives:read and sharing:read but (apparently) no drives:write / sharing:write. An agent can write content into a drive a human created, but cannot create its own drive or publish a share link. Maybe that's an intentional least-privilege stance - but it means every new agent onboarding needs a human in the console first.

Ask: decide whether that's intended. If yes, document it as the onboarding model ("human creates the drive, mints a content+changes token"). If not, add a drives:write scope.

4. What worked cleanly

• Console-minted, audience-bound Bearer token authenticated against https://drive.tokencanopy.com on the first call.
• GET /v0/drives returned 200 with the workspace drive list.
• Multipart artifact create returned 201 with full metadata (id, head_version_id, revision), and GET /v0/drives/{id}/artifacts/{artifact_id}/content read the bytes back exactly.

Environment: direct REST (no SDK), token scopes drives:read content:read content:write changes:read sharing:read usage:read.