Authentication

Use an API key for API requests. Send it as a bearer token in the Authorization header:

export AGENTFS_KEY="afs_..."

curl -sS https://agentfs.cloud/v1/me \
  -H "Authorization: Bearer $AGENTFS_KEY"

Keep the key in a secret store. Do not put it in a URL, uploaded file, log, browser code, or user-visible response. A revoked or expired key returns 401 unauthorized.

Create a key in the dashboard

1. Sign in at agentfs.cloud.
2. Open the project that should own the files.
3. Open API Keys, then select Create key.
4. Give the key a name.
5. Copy the secret immediately. The full value is not shown again.

A key made in the dashboard only reaches its project, and uploads without a path go to that project. Revoke a key from the same page; it stops working immediately.

Identify an agent

Add these optional headers when you want audit entries to identify a caller:

curl -sS https://agentfs.cloud/v1/me \
  -H "Authorization: Bearer $AGENTFS_KEY" \
  -H "X-Agent-ID: report-agent" \
  -H "X-Run-ID: run-42" \
  -H "X-Session-ID: session-9"

Each value must contain 1–128 printable characters.

Connect with device authorization

Use the device flow when an agent cannot safely ask you for a key.

1. Request a device code

No key is needed:

curl -sS -X POST https://agentfs.cloud/v1/auth/device

The response includes a device code, a user code, and a page for approval:

{
  "device_code": "device-code-example",
  "user_code": "7K2M-4Q9R",
  "verification_uri": "https://agentfs.cloud/device",
  "verification_uri_complete": "https://agentfs.cloud/device?code=7K2M-4Q9R",
  "expires_in": 900,
  "interval": 5,
  "next": "Show the verification URL and code to the user, then poll the token endpoint every 5 seconds."
}

Show verification_uri_complete and user_code to the person who owns the account. They open the page, sign in, enter the code, and optionally select a default project.

2. Poll for approval

Poll no more often than the returned interval:

curl -sS -X POST https://agentfs.cloud/v1/auth/device/token \
  -H "content-type: application/json" \
  -d '{"device_code":"device-code-example"}'

Before approval, the endpoint returns 428 authorization_pending and a Retry-After header. Polling too soon returns 429 slow_down; use its Retry-After value. The device code expires after 15 minutes.

After approval, save the key from the response at once:

{
  "type": "account",
  "id": "org_7ab1",
  "api_key": "afs_...",
  "default_project": "research",
  "next": "Store this value as AGENTFS_KEY. It will not be shown again."
}

Use the returned value as AGENTFS_KEY for later requests. A denied, expired, claimed, or unknown code returns a problem response.