Update a credential
Changes what is sent and keeps the rest; type cannot change. A change of origins that adds a site (or, for a secret, removes the limit), and a scope/shell that makes an AI-only credential readable by shells, needs the sensitive values in the same request (a secret's value; a password's password, and totpSecret when it has 2FA), and so does a change of codeSource or codeUrl (the password), and applies only if the sites, scope, shell, codeSource and codeUrl did not change meanwhile (409 conflict). A new codeUrl answers with a new codeUrlSecret once, and so does rotateCodeUrlSecret: true (any time; the old one stops at once). Sessions that export the credential get the new values on their next machine (resume or recovery); runs already working keep the ones they started with.
PATCH
/v1/credentials/{name}Request
| Method and path | PATCH/v1/credentials/{name} |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
| Rate limit | Yes. See Rate limits for the numbers and headers. |
Path parameters
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
namerequired | string | – | – | Up to 64 characters. Pattern: ^[A-Z_][A-Z0-9_]*$. |
Body
JSON with content-type: application/json. Required.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
origins | string[] | null | – | – | null (any site) for a secret only. 1 to 20 items. |
username | string | – | – | 1 to 320 characters. |
password | string | – | – | 1 to 1024 characters. |
totpSecret | string | null | – | – | A new 2FA setup key or otpauth://totp/ link; null removes 2FA. |
codeSource | string | null | – | totp, push, url, null | Changing it needs the password again. |
codeUrl | string | – | – | Changing it needs the password again; answers with a new codeUrlSecret. Up to 2048 characters. |
codeTimeoutSeconds | integer | – | – | From 5 to 900. |
value | string | – | – | 1 to 8000 characters. |
description | string | null | – | – | Up to 500 characters. |
shell | boolean | – | – | |
scope | string | agent | agent, shell, all | agent: only the AI, as placeholders (agent runs, steps, scripts' step(), the type action); shell: only as environment variables in session shells and commands; all: both. |
rotateCodeUrlSecret | boolean | – | – | A new codeUrl signing secret |
curl -X PATCH https://api.boxline.dev/v1/credentials/$CREDENTIAL_NAME \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -d '{"password": "'"$NEW_PASSWORD"'"}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLawait bx.credentials.update("SHOP", { password: process.env.NEW_PASSWORD! }); // the sites, user name and 2FA are kept// A new secret for codeUrl requests: shown only now, and the old one stops at once.const { codeUrlSecret } = await bx.credentials.update("SHOP", { rotateCodeUrlSecret: true });import osfrom boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLbx.credentials.update("SHOP", password=os.environ["NEW_PASSWORD"]) # the sites, user name and 2FA are kept# A new secret for codeUrl requests: shown only now, and the old one stops at once.code_url_secret = bx.credentials.update("SHOP", rotate_code_url_secret=True)["codeUrlSecret"]Responses
200 OK
The credential.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
name | string | – | – | |
type | string | – | password, secret | |
description | string | null | – | – | |
origins | string[] | null | – | – | Sites where the AI may type it (null = any site; always set for a password). |
username | string | – | – | A password's user name. |
hasTotp | boolean | – | – | A password has a 2FA key (codeSource totp). |
codeSource | string | null | – | totp, push, url, null | Where a password's 2FA codes come from (%NAME.otp%, boxline-otp NAME); null: no 2FA. |
codeUrl | string | null | – | – | The endpoint the platform asks for codes (codeSource url). |
codeTimeoutSeconds | integer | – | – | How long a wait for a pushed or asked code lasts. From 5 to 900. |
preview | string | null | – | – | A secret's last 4 characters, for values of 24 characters or more; null for shorter values and for secrets with origins. |
shell | boolean | – | – | The AI may use it in bash commands; this also allows exporting it into shells. |
scope | string | agent | agent, shell, all | agent: only the AI, as placeholders (agent runs, steps, scripts' step(), the type action); shell: only as environment variables in session shells and commands; all: both. |
createdAt | string | – | – | Format: date-time. |
updatedAt | string | – | – | Format: date-time. |
lastUsedAt | string | null | – | – | Format: date-time. |
codeUrlSecret | string | – | – | Signs the platform's requests to codeUrl (Boxline-Signature |
{ "name": "SHOP", "type": "password", "description": "…", "origins": [ "…" ], "username": "…", "hasTotp": false, "codeSource": "totp", "codeUrl": "…", "codeTimeoutSeconds": 5, "preview": "••••1a2b", "shell": false, "scope": "agent", "createdAt": "2026-09-29T10:00:00.000Z", "updatedAt": "2026-09-29T10:00:00.000Z", "lastUsedAt": "2026-09-29T10:00:00.000Z", "codeUrlSecret": "whsec_…"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 402 Payment Required | feature_not_in_plan, spend_limit, out_of_credit, plan_limit, spend_limit, out_of_credit, organization, project, plan, credit | The plan does not include this, a monthly allowance or spending limit is used up, the organization has no credit left, or the plan allows no more of this. spend_limit and out_of_credit carry error.details.limit: organization, project, plan or credit. |
| 404 Not Found | not_found, invite_not_found, provider_unavailable | No such thing in this project (or organization), or no such route. |
| 409 Conflict | session_not_running, shell_disabled, browser_disabled, nothing_saved, not_resumable, invalid_state, conflict, email_taken, identity_in_use, provider_already_linked, last_sign_in_method, not_impersonating, machine_too_old, too_many_credential_values, limit_reached, terms_version_mismatch, no_project, last_owner, organization_not_empty, project_has_sessions, already_member, invite_pending, idempotency_in_progress | The current state does not allow it, or a request with this Idempotency-Key is still being answered. |
| 429 Too Many Requests | rate_limited, concurrency_limit | Too many requests, or the organization's concurrent sessions (its plan's) or the project's concurrencyCap are in use. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.