diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index d1e74fc..d1e4268 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -3,8 +3,8 @@ title: Error codes description: API error response fields and stable error codes. type: reference audience: user -verified: 2026-07-28 -product_version: 0.25.0 +verified: 2026-08-14 +product_version: 0.26.2 executable: false --- @@ -51,7 +51,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The supplied identifier does not match the expected version 7 universally unique identifier shape. | Use identifiers returned by agentsfleet. | +| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The identifier is not a valid version 7 universally unique identifier (UUID). | Use identifiers returned by agentsfleet. | ### Service failures @@ -84,10 +84,10 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-004` | 503 | Authentication service unavailable | Authentication service is temporarily unavailable. Retry shortly. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-005` | 404 | Session not found | Session was not found. It may have expired or been invalidated. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-006` | 401 | Session expired | Your session has expired. Please sign in again. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit verification code did not match what the dashboard issued. Double-check the code shown in your browser and try again. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit code does not match the one shown in your browser. Re-enter it and try again. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-012` | 410 | Login session already consumed | This login session has already been consumed. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted (too many wrong codes, explicit cancel, or replaced by a newer session). Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-014` | 409 | Login session not approved | This login session has not been approved in the dashboard yet. Approve it in your browser before submitting a verification code. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted: too many wrong codes, a cancel, or a newer session. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-014` | 409 | Login session not approved | This login session is not approved yet. Approve it in your browser, then submit the code. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-015` | 409 | Login session already approved | This login session has already been approved. Do not call /approve a second time. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-016` | 400 | Invalid command-line public key | The supplied public_key is malformed. Expect base64url-encoded P-256 SubjectPublicKeyInfo. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-017` | 400 | Invalid token name | token_name must contain 1 to 64 characters from space through tilde. | Keep sign-in sessions and credentials current. | @@ -95,19 +95,16 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-023` | 401 | Command-line credential revoked | This credential was revoked by a logout or by a newer login from this machine. Run `agentsfleet login` to get a new one. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-024` | 404 | Command-line credential not found | You have no live credential with that identifier. It may be revoked, or it may not be yours. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-025` | 401 | Credential exchange failed | Login could not exchange the browser session for a durable credential, so nothing was saved. The session likely expired. Run `agentsfleet login` again. | Keep sign-in sessions and credentials current. | ### API | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-API-001` | 429 | Too many requests | The API is handling its maximum number of requests. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | -| `UZ-API-002` | 503 | Activity stream capacity reached | The API is serving its maximum number of activity streams. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | - -### Fleet keys - -| Code | HTTP | Title | Why and fix | Prevent | -|---|---|---|---|---| -| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key not found. Verify the fleet_key_id. | Use a current Fleet API key for the intended fleet. | +| `UZ-API-001` | 429 | Too many requests | The API is at its request limit. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | +| `UZ-API-002` | 503 | Activity stream capacity reached | The API is at its activity-stream limit. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | ### Webhooks @@ -115,22 +112,22 @@ A conflict response also contains `current_state`. Some errors contain `user_mes |---|---|---|---|---| | `UZ-WH-001` | 404 | Fleet not found for webhook | No fleet is registered for this webhook endpoint. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-010` | 401 | Invalid webhook signature | Webhook signature verification failed. Confirm the signing secret stored for this provider (Slack/Clerk/other) matches the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook request timestamp is outside the allowed 5-minute drift window. This may indicate a replay attack or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret with at least 32 bytes. Store it as this source's webhook_secret, configure the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace before redelivering the event. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-010` | 401 | Invalid webhook signature | The webhook signature did not verify. The stored signing secret must match the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-011` | 401 | Stale webhook timestamp | The webhook timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret of at least 32 bytes. Store it as this source's webhook_secret, set the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace, then redeliver the event. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload size or filter at the source. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-030` | 413 | Webhook payload too large | The webhook body exceeds the 1 MiB limit. Reduce the payload size. | Keep webhook signing secrets matched and service clocks synchronized. | ### Slack | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature did not verify. Confirm the platform Slack app signing secret matches the one vaulted at slack-app/signing_secret. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the allowed 5-minute drift window — a replay attempt or a skewed server clock. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install, so the event is acknowledged (200) and ignored. Re-run Connect Slack in the dashboard to (re)install. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if the error continues, verify the platform Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing chat:write, a 429, or a Slack outage). It is logged and retried with backoff; the run itself never fails. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack signature did not verify. The Slack app's signing secret must match the one vaulted at slack-app/signing_secret. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-020` | 200 | Slack team not installed | This Slack team has no connector install; the event is acknowledged and ignored. Re-run Connect Slack from the dashboard. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it continues, check the Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-030` | 502 | Slack answer post failed | The answer could not be posted to Slack: missing chat:write, a 429, or an outage. It retries with backoff; the run does not fail. | Keep Slack app credentials, permissions, and clocks current. | ### Tools @@ -152,6 +149,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AGT-012` | 409 | Fleet is paused | This Fleet is paused. Resume it before sending new work. | Use fleet identifiers from the current workspace. | | `UZ-AGT-013` | 500 | Fleet install rolled back | We couldn't finish setting up your fleet. Nothing was created — try again. | Use fleet identifiers from the current workspace. | | `UZ-AGT-014` | 412 | Fleet source is stale | Someone else edited this Fleet's source since you opened it. Reload to see their change, then re-apply your edit. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-015` | 404 | Event not found | We couldn't find that event. It may have aged out, or the identifier doesn't match one on this Fleet. | Use fleet identifiers from the current workspace. | ### Schedules @@ -263,7 +261,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-RUN-012` | 402 | Lease renewal blocked: no credits | The tenant balance cannot cover another run slice. The lease does not renew, and the run stops cleanly. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-013` | 400 | Renew body malformed | The renew request body could not be parsed. Token counts become zero, but the renewed slice still charges for runtime. The lease still renews. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-014` | 404 | Runner not found | We couldn't find that runner. It may have been removed — refresh the list. | Keep runner settings and lease health within configured limits. | -| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily_dollars or monthly_dollars limit from `TRIGGER.md`. The lease cannot renew, so the run stops. This differs from UZ-RUN-012, which reports a low tenant balance. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily_dollars or monthly_dollars limit from `TRIGGER.md`, so the run stops. The tenant balance is fine; this is the fleet's own budget. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-016` | 409 | Active runner must be revoked before deletion | This runner is still live. Revoke it first, then delete it. | Keep runner settings and lease health within configured limits. | ### Runs @@ -283,7 +281,8 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-EXEC-013` | 500 | Runner fleet run failed | The runner could not finish the fleet run. Check the activity stream. | Check runner settings and access before starting work. | | `UZ-EXEC-014` | 400 | Run settings invalid | The run settings are invalid. Check the fleet files before retrying. | Check runner settings and access before starting work. | | `UZ-EXEC-015` | 402 | Run stopped: fleet limit reached | The run stopped because the fleet reached its configured limit. | Check runner settings and access before starting work. | -| `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's agt_r runner token (401/403) on the heartbeat. Retrying can't fix it — mint a fresh agt_r and issue the host's runner token again, then restart the runner. | Check runner settings and access before starting work. | +| `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's runner token. Retrying cannot fix it: mint a fresh agt_r token, re-issue the host's runner token, and restart the runner. | Check runner settings and access before starting work. | +| `UZ-EXEC-017` | 409 | Assignment exceeds host capability | The assigned policy needs an enforcement mechanism this host cannot deliver. The runner row names it. Fix the host or relax the assignment. | Check runner settings and access before starting work. | ### Approvals @@ -300,7 +299,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or does not belong to the requesting workspace. Verify the fleet_id and workspace scope. | Use an existing fleet and a valid memory category. | +| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or is not in this workspace. Verify both. | Use an existing fleet and a valid memory category. | | `UZ-MEM-003` | 503 | Saved memory unavailable | Saved memory is unavailable. The fleet uses temporary workspace memory until the service recovers. | Use an existing fleet and a valid memory category. | | `UZ-MEM-004` | 404 | Memory entry not found | That memory entry is already gone — the fleet isn't holding anything under that key. | Use an existing fleet and a valid memory category. | @@ -308,19 +307,29 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/workspaces/{ws}/fleet-keys` | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/api-keys` | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-003` | 404 | API key not found | We couldn't find that API key. It may have already been deleted — refresh the list. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-004` | 401 | API key has been revoked | This key was revoked and can no longer authenticate. Mint a replacement with: POST /v1/api-keys | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | An API key with that name already exists. Pick a different name for this tenant. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-006` | 409 | API key is already revoked | That API key is already revoked. Refresh the list to see its current state. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | A revoked key can't be reactivated. Mint a new key instead. | Use current API key identifiers and replace revoked keys. | -| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke this key before deleting it. Revoke it first, then delete the revoked key. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | This key is still active. Revoke it first, then delete it. | Use current API key identifiers and replace revoked keys. | + +### Repository repair + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-REPAIR-010` | 403 | Write mint requires an approved gate | No repository-write approval was answered for this event, so no write-scoped token issues. The run continues read-only. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-011` | 403 | Fleet binding changed since approval | The fleet's repository binding no longer matches the approved card. Re-raise the approval so a human sees the current reach. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-012` | 200 | Duplicate repair link refused | A repair Pull Request already links this incident, so a second one is acknowledged and not recorded. Close the surplus Pull Request on GitHub. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-013` | 403 | Write request allowance exhausted | This approval already funded 32 write-credential requests. Answer a new repository-write approval first. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-014` | 200 | Repair provenance refused | The repair branch does not match an approved write gate on workspace, Fleet, event, installation, repository, and App author. The delivery is acknowledged and nothing is recorded. | Have a human approve the repository-write gate before the run mints a write-scoped token. | ### Integration grants | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with: `POST /v1/workspaces/{ws}/fleets/{id}/integration-requests` | Use active integration grants approved for the fleet. | +| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Check it with `GET /v1/workspaces/{ws}/fleets/{id}/integration-grants` and resolve its approval. | Use active integration grants approved for the fleet. | | `UZ-GRANT-002` | 404 | Integration grant not found | We couldn't find that grant request. It may have already been resolved — refresh the list. | Use active integration grants approved for the fleet. | | `UZ-GRANT-003` | 409 | Grant already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Use active integration grants approved for the fleet. | @@ -329,22 +338,14 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| | `UZ-CRED-001` | 404 | Integration not connected | That integration isn't connected. Connect it from the Integrations page, then try again. | Create required workspace secrets before starting a run. | -| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not wired on this deployment (a boot-time misconfiguration, not a client error). An operator must configure it before runners can mint credentials. | Create required workspace secrets before starting a run. | +| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not configured on this deployment. An operator must set it up before runners can mint credentials. | Create required workspace secrets before starting a run. | ### GitHub | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | Keep the GitHub App installed with required repository access. | -| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). This is temporary. Retry shortly; if the error continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. | - -### Repairs - -| Code | HTTP | Title | Why and fix | Prevent | -|---|---|---|---|---| -| `UZ-REPAIR-010` | 403 | Write mint requires an approved gate | A write-scoped repository token issues only when this run's event carries an approved repository-write gate. No card was answered for this event, or it resolved to something other than approved — the run continues read-only. Answer the approval card, then let the fleet retry. | Approve the repository-write card before the fleet writes. | -| `UZ-REPAIR-011` | 403 | Fleet binding changed since approval | The fleet's repository binding no longer matches the one the approval card stated. Re-raise the approval so a human sees the current reach — the mint refuses rather than widening a decided answer. | Approve the repository-write card before the fleet writes. | -| `UZ-REPAIR-012` | 200 | Duplicate repair link refused | A repair Pull Request already links this incident, so a second one is acknowledged and not recorded. The first shipped repair is the record; close the surplus Pull Request on GitHub. | Let one repair Pull Request carry each incident. | +| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation was uninstalled or revoked, so no token can be minted. Reconnect GitHub from the dashboard. | Keep the GitHub App installed with required repository access. | +| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token. Retry shortly; if it continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. | ### Connectors diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 60c6fc8..60b7a65 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -3,8 +3,8 @@ title: API introduction description: Base URL, authentication, errors, and common response formats. type: explanation audience: user -verified: 2026-07-22 -product_version: 0.25.0 +verified: 2026-08-14 +product_version: 0.26.2 executable: false --- @@ -24,7 +24,9 @@ Use the API when a script or service needs direct access. Use the command-line c Most paths accept a bearer token in the `Authorization` header. Tenant API keys start with `agt_t` and are shown once when created. -Interactive users can sign in with `agentsfleet login`. The login flow saves a short-lived JSON Web Token (JWT). +Interactive users sign in with `agentsfleet login`. Login saves a durable command-line credential that starts with `afc_`. The credential resolves to the person who signed in. + +The credential stays valid until a logout, a newer login from the same computer, or a dashboard revoke ends it. Webhook and connector paths use provider signatures instead of bearer tokens. The OpenAPI security section on each operation states the required method. diff --git a/api-reference/scopes.mdx b/api-reference/scopes.mdx index 81d0665..0604ed7 100644 --- a/api-reference/scopes.mdx +++ b/api-reference/scopes.mdx @@ -3,8 +3,8 @@ title: API scopes description: Permissions that an agentsfleet access token can carry. type: reference audience: user -verified: 2026-07-12 -product_version: 0.25.0 +verified: 2026-08-14 +product_version: 0.26.2 executable: false --- @@ -40,8 +40,6 @@ curl -s https://api.agentsfleet.net/v1/fleets -H 'Authorization: Bearer af_test_ | `apikey:read` | Lists tenant API keys. | `apikey:write`, `apikey:admin` | | `apikey:write` | Creates and rotates tenant API keys. | `apikey:admin` | | `apikey:admin` | Revokes tenant API keys. | None | -| `fleetkey:read` | Lists fleet keys. | `fleetkey:write` | -| `fleetkey:write` | Creates and deletes fleet keys. | None | | `grant:read` | Lists integration grants. | `grant:write` | | `grant:write` | Revokes integration grants. | None | | `connector:read` | Reads connector state. | `connector:write` | @@ -50,7 +48,7 @@ curl -s https://api.agentsfleet.net/v1/fleets -H 'Authorization: Bearer af_test_ | `workspace:admin` | Creates and lists workspaces. | None | | `library:write` | Adds an entry to a workspace library. | None | | `platform-library:write` | Adds an entry to the platform library. | None | -| `approval:read` | Reads pending approvals. | None | +| `approval:read` | Reads pending approvals. | `approval:resolve` | | `approval:resolve` | Approves or denies a request. | None | Operator tokens may carry `runner:*`, `platform-key:*`, `platform-library:*`, `model:*`, or `workspace:any`. Tenant integrations do not need these scopes. diff --git a/billing/budgets.mdx b/billing/budgets.mdx index d6e94a0..a09150e 100644 --- a/billing/budgets.mdx +++ b/billing/budgets.mdx @@ -4,7 +4,7 @@ description: Daily and monthly spending limits for one fleet. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/changelog.mdx b/changelog.mdx index f237a85..805fa5b 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,6 +7,31 @@ description: "Stay up to date with the latest agentsfleet product updates, new f agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## Login saves a credential that outlives the browser session + + `agentsfleet login` used to save the browser session token it recovered, and that token is valid for about a minute. A terminal went stale while its operator was still reading the success message, and no renewal path exists. Login now spends that minute exchanging the session for a durable `afc_` credential, and the credential is what reaches disk. It resolves to the person who signed in rather than to the tenant, so an audit trail records who ran a command instead of a free-text label. + + ## Breaking changes + + - **`agentsfleet login --token` is gone.** The flag is refused as an unknown option rather than ignored. Piped input goes with it: a login with no terminal attached and no `AGENTSFLEET_API_KEY` fails and names that variable. Unattended callers set `AGENTSFLEET_API_KEY` to a tenant API key, which authenticates every request and writes nothing to disk. + - **`agentsfleet logout` no longer ends your dashboard session.** It revokes this computer's credential, aborts any unfinished sign-in, and clears local state. A browser session is a different credential class that refreshes through the identity provider, so signing out of a terminal leaves the dashboard you are reading signed in. A revoke that cannot reach the server still clears local state, and warns that the credential stays live until you revoke it from the dashboard. + - **A deployment that sets `OIDC_PROVIDER=custom` is refused at boot.** The value selected a second ladder that read capability and workspace claims from `custom_claims`, `app_metadata`, and namespaced keys, none of which anything writes. `OIDC_PROVIDER=clerk` is unchanged, so no deployment that runs today needs editing. + + ## What's new + + - **One live credential per computer.** A second login from the same computer revokes what it left behind, and `core.cli_credentials` carries a partial unique index, so two live credentials for one person and computer cannot be recorded at all. Only a hash is stored, so the credential cannot be read back from anywhere. `agentsfleet logout` is how a computer ends its own. + - **A credential records the server that issued it.** Later commands reach that server with no flag and no environment variable. The order is `--api`, then `AGENTSFLEET_API_URL`, then the recorded server, then the built-in URL. A saved credential that records no server, dialed at a server nobody named, is refused before anything is sent, with error code `DEPLOYMENT_UNKNOWN` and exit code `1`. The `logout` and `doctor` commands still run, because one ends a credential and the other explains the refusal. + - **Three error codes name what went wrong.** `UZ-AUTH-023` says the credential was revoked, `UZ-AUTH-024` says no live credential of yours has that identifier, and `UZ-AUTH-025` says login recovered a session but could not exchange it, so nothing was saved. A `401` or `403` from the client now names the API URL the credential was presented to. + + ## Security + + - **Minting a credential takes a browser sign-in.** A credential still authenticates listing and revoking, so a terminal can end its own access without opening a browser, but it cannot mint a replacement. Minting used to accept an existing credential, which turned one stolen credential into an unbounded supply under machine names of the caller's choosing. + - **A stored value is checked against its whole shape.** The load path and the mint response both require `afc_` followed by exactly 64 lower-case hexadecimal characters. A prefix check passed values carrying trailing bytes. + - **A tenant API key carries its creator's capabilities.** An `agt_t` key resolves its capability set from the identity provider, keyed on the `created_by` subject the key already stored, instead of a nine-entry set compiled into the binary that no operator could narrow. Narrowing that person narrows every key they minted, on the next request past the cache window. A creator the provider no longer knows resolves to no capability, and an unreachable provider past the staleness ceiling reports unavailable rather than an empty grant. + - **Each claim is read from exactly one key.** The capability claim is `scopes` and nothing else. The reader used to try OAuth2's `scope` first, so a token carrying both would have supplied a capability set we never granted, on the authorisation path. The `scp` spelling and the `workspaceId` alias are unread. + + ## Metered runs are priced from the model catalogue diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index 2613a80..9d0908d 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -3,8 +3,8 @@ title: Command reference description: Commands available in the agentsfleet command-line client. type: reference audience: user -verified: 2026-07-12 -product_version: 0.25.0 +verified: 2026-08-14 +product_version: 0.26.2 executable: false --- @@ -63,8 +63,8 @@ Commands: | Command | Effect | |---|---| -| `agentsfleet login` | Signs in through a browser or supplied token. | -| `agentsfleet logout` | Revokes every active session and clears local credentials. | +| `agentsfleet login` | Signs in through a browser and saves a durable credential for this computer. | +| `agentsfleet logout` | Revokes this computer's credential and any unfinished sign-in, then clears local credentials. Browser sessions stay signed in. | | `agentsfleet auth status` | Shows the token source, claims, and server status. | | `agentsfleet doctor` | Checks client settings, authentication, and API access. | @@ -78,9 +78,6 @@ Commands: | `agentsfleet workspace show [WORKSPACE_ID]` | Shows one workspace. | | `agentsfleet workspace secrets` | Prints the secret command and dashboard path. | | `agentsfleet workspace delete ` | Removes one workspace from local client state. Remote data remains. | -| `agentsfleet fleet-key create` | Creates a key bound to one fleet. The raw key appears once. | -| `agentsfleet fleet-key list` | Lists fleet keys without raw values. | -| `agentsfleet fleet-key delete ` | Revokes a fleet key. Calls using that key fail. | | `agentsfleet api-key create` | Creates a tenant API key. The raw key appears once. | | `agentsfleet api-key list` | Lists tenant API keys. | | `agentsfleet api-key revoke ` | Revokes a tenant API key. Calls using that key fail. | diff --git a/cli/configuration.mdx b/cli/configuration.mdx index b9771d9..45eea16 100644 --- a/cli/configuration.mdx +++ b/cli/configuration.mdx @@ -3,8 +3,8 @@ title: Client configuration description: Environment variables and value order for the agentsfleet client. type: reference audience: user -verified: 2026-07-12 -product_version: 0.25.0 +verified: 2026-08-14 +product_version: 0.26.2 executable: false --- @@ -14,7 +14,9 @@ executable: false The client reads command options, environment variables, saved login data, and built-in defaults. A value earlier in the documented order wins. -For authentication, `AGENTSFLEET_API_KEY` overrides the saved login token. The `login` command accepts `--token`, piped input, or browser approval. +For authentication, `AGENTSFLEET_API_KEY` overrides the saved login credential. The `login` command approves in a browser. It accepts no token on the command line and reads no token from piped input. + +Login also records the server it signed into. Later commands reach that same server unless you name another one. ## Example with output @@ -32,22 +34,26 @@ AGENTSFLEET_API_URL=https://api.agentsfleet.net agentsfleet --version |---|---|---|---| | `AGENTSFLEET_API_URL` | Sets the API base URL. | `https://api.agentsfleet.net` | URL beginning with `http://` or `https://` | | `AGENTSFLEET_DASHBOARD_URL` | Sets the browser login URL. | `https://app.agentsfleet.net` | URL beginning with `http://` or `https://` | -| `AGENTSFLEET_API_KEY` | Authenticates every request and overrides saved login data. | None | Valid tenant API key | +| `AGENTSFLEET_API_KEY` | Authenticates every request and overrides saved login data. Nothing is written to disk. | None | Valid tenant API key starting with `agt_t` | | `AGENTSFLEET_STATE_DIR` | Stores local credentials, settings, and telemetry consent. | `~/.config/agentsfleet` | Writable directory path | | `NO_COLOR` | Disables coloured output when set to `1`. | Unset | `1` or unset | | `AGENTSFLEET_TELEMETRY_DISABLED` | Disables usage telemetry when set to `1`. | Unset | `1` or unset | | `DO_NOT_TRACK` | Disables usage telemetry when set to `1`. | Unset | `1` or unset | | `AGENTSFLEET_TELEMETRY_DEBUG` | Prints telemetry details to standard error when set to `1`. | Unset | `1` or unset | -The API URL uses this order: `--api`, `AGENTSFLEET_API_URL`, `.env.local`, then the built-in URL. +The API URL uses this order: `--api`, `AGENTSFLEET_API_URL`, the server recorded at login, then the built-in URL. ## Errors -An invalid URL returns exit code `4`. A missing token returns exit code `1`. +An invalid URL returns exit code `4`. A missing credential returns exit code `1`. A network failure returns exit code `2`. The client does not change saved login data after a network failure. -Do not put tokens in command history. Use `AGENTSFLEET_API_KEY` through your secret manager for unattended commands. +A saved credential that records no server returns exit code `1` with error code `DEPLOYMENT_UNKNOWN`. Nothing is sent. Pass `--api `, set `AGENTSFLEET_API_URL`, or run `agentsfleet login` again. + +The `logout` and `doctor` commands still run in that state. One ends a credential and the other explains the refusal. + +Do not put credentials in command history. Use `AGENTSFLEET_API_KEY` through your secret manager for unattended commands. ## Related pages diff --git a/cli/flags.mdx b/cli/flags.mdx index 4e350e0..3edfed3 100644 --- a/cli/flags.mdx +++ b/cli/flags.mdx @@ -4,7 +4,7 @@ description: Options accepted by the agentsfleet command-line client. type: reference audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: true --- diff --git a/cli/install.mdx b/cli/install.mdx index 427c50a..8d7f92b 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -4,7 +4,7 @@ description: Install and remove the agentsfleet command-line client. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: true --- diff --git a/concepts.mdx b/concepts.mdx index 699c230..a78727f 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -4,7 +4,7 @@ description: Understand tenants, workspaces, fleets, tools, events, and runs. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/concepts/context-lifecycle.mdx b/concepts/context-lifecycle.mdx index 3d53f6e..10103ca 100644 --- a/concepts/context-lifecycle.mdx +++ b/concepts/context-lifecycle.mdx @@ -4,7 +4,7 @@ description: Learn how a fleet keeps useful context during long runs. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/docs.json b/docs.json index 4e8e340..8ef1d8b 100644 --- a/docs.json +++ b/docs.json @@ -125,7 +125,9 @@ "POST /v1/auth/sessions/{session_id}/verify", "DELETE /v1/auth/sessions/{session_id}", "DELETE /v1/auth/sessions/all", - "POST /v1/auth/identity-events/clerk" + "POST /v1/auth/identity-events/clerk", + "POST /v1/cli-credentials", + "DELETE /v1/cli-credentials/{id}" ] }, { diff --git a/fleets/authoring.mdx b/fleets/authoring.mdx index 88d4c09..a082307 100644 --- a/fleets/authoring.mdx +++ b/fleets/authoring.mdx @@ -4,7 +4,7 @@ description: Create the two files that define a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/connectors.mdx b/fleets/connectors.mdx index f702d8f..d520002 100644 --- a/fleets/connectors.mdx +++ b/fleets/connectors.mdx @@ -4,7 +4,7 @@ description: Connect a workspace to GitHub, Slack, Zoho Desk, Jira, or Linear. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/install.mdx b/fleets/install.mdx index f8d3943..d34b5cc 100644 --- a/fleets/install.mdx +++ b/fleets/install.mdx @@ -4,7 +4,7 @@ description: Install a fleet from your workspace library. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/library.mdx b/fleets/library.mdx index 99caf6b..3b39d5e 100644 --- a/fleets/library.mdx +++ b/fleets/library.mdx @@ -4,7 +4,7 @@ description: Understand platform and workspace library entries. type: explanation audience: user verified: 2026-08-10 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/overview.mdx b/fleets/overview.mdx index 64125f1..67c2cca 100644 --- a/fleets/overview.mdx +++ b/fleets/overview.mdx @@ -4,7 +4,7 @@ description: Understand what a fleet owns and how its lifecycle works. type: explanation audience: user verified: 2026-07-21 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/running.mdx b/fleets/running.mdx index dc3479f..242af7b 100644 --- a/fleets/running.mdx +++ b/fleets/running.mdx @@ -4,7 +4,7 @@ description: Inspect, message, stop, resume, kill, and delete a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/secrets.mdx b/fleets/secrets.mdx index b2b9372..95860df 100644 --- a/fleets/secrets.mdx +++ b/fleets/secrets.mdx @@ -4,7 +4,7 @@ description: Store, replace, inspect, and delete workspace secrets. type: how-to audience: user verified: 2026-07-29 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/tools.mdx b/fleets/tools.mdx index 1f5d659..f6d560f 100644 --- a/fleets/tools.mdx +++ b/fleets/tools.mdx @@ -4,7 +4,7 @@ description: Understand the tools that a fleet can call. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/troubleshooting.mdx b/fleets/troubleshooting.mdx index e3dfde5..291a9a7 100644 --- a/fleets/troubleshooting.mdx +++ b/fleets/troubleshooting.mdx @@ -4,7 +4,7 @@ description: Find and fix common fleet failures. type: troubleshooting audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/webhooks.mdx b/fleets/webhooks.mdx index 667ad79..67cf7d8 100644 --- a/fleets/webhooks.mdx +++ b/fleets/webhooks.mdx @@ -4,7 +4,7 @@ description: Send signed provider events to a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/index.mdx b/index.mdx index 6326035..bf6293e 100644 --- a/index.mdx +++ b/index.mdx @@ -4,7 +4,7 @@ description: Create and run event-driven fleets. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/memory.mdx b/memory.mdx index 254b909..d76c60b 100644 --- a/memory.mdx +++ b/memory.mdx @@ -4,7 +4,7 @@ description: Learn what a fleet can remember between events. type: explanation audience: user verified: 2026-07-18 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/quickstart.mdx b/quickstart.mdx index acbb9f7..8a85b85 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,7 +4,7 @@ description: Install your first fleet and send it a GitHub event. type: tutorial audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/scripts/check-documentation.py b/scripts/check-documentation.py index 74b5b6f..2aa516b 100755 --- a/scripts/check-documentation.py +++ b/scripts/check-documentation.py @@ -100,7 +100,7 @@ "UDP", "URL", } -EXPECTED_VERSION = "0.25.0" +EXPECTED_VERSION = "0.26.2" NON_PAGE_CODE_SNIPPETS = {Path("snippets/rates.mdx")} ERROR_REFERENCE_PRIVATE_TERMS = { "API_MAX_", diff --git a/scripts/test-documentation.py b/scripts/test-documentation.py index 4da6bec..8b35471 100755 --- a/scripts/test-documentation.py +++ b/scripts/test-documentation.py @@ -24,7 +24,7 @@ type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/workspaces/managing.mdx b/workspaces/managing.mdx index 16b1098..20d1a60 100644 --- a/workspaces/managing.mdx +++ b/workspaces/managing.mdx @@ -4,7 +4,7 @@ description: Create, select, inspect, and remove local workspace entries. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/workspaces/overview.mdx b/workspaces/overview.mdx index 41293a5..6fce855 100644 --- a/workspaces/overview.mdx +++ b/workspaces/overview.mdx @@ -4,7 +4,7 @@ description: Understand what a workspace owns and separates. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false ---