Create a credential
A website password (type: "password": sites, user name, password and an optional code source: totp with a 2FA key, push or url; needs the plan's loginDetails) or a secret (type: "secret": one value). Each field is sealed (AES-256-GCM under the platform's secrets key) and never returned. 409 credential_exists for a name the project has (change it with PATCH), 402 plan_limit beyond the plan's maxCredentials (200 by default), 400 code_url_not_allowed for a codeUrl that is not a public HTTPS address (503 code_url_unavailable when this platform cannot send codeUrl requests). Setting codeUrl answers with codeUrlSecret once. 60 writes per minute per project.
POST
/v1/credentialsRequest
| Method and path | POST/v1/credentials |
|---|---|
| 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. |
Body
JSON with content-type: application/json. Required.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
namerequired | string | – | – | Capitals, digits and _ (not PATH, HOME, BOXLINE_*, SANDBOXD_*, BASH_*). Up to 64 characters. |
typerequired | string | – | password, secret | |
origins | string[] | – | – | Sites, "https://example.com" or "https://*.example.com" (any subdomain). Required for a password. 1 to 20 items. |
username | string | – | – | 1 to 320 characters. |
password | string | – | – | 1 to 1024 characters. |
totpSecret | string | – | – | The site's 2FA setup key (base32, spaces allowed) or an otpauth://totp/ link from its QR code. TOTP (RFC 6238): SHA-1, 30 s and 6 digits unless the link says otherwise. Alone it means codeSource totp. |
codeSource | string | null | – | totp, push, url, null | totp (needs totpSecret), push (POST /v1/credentials/:name/codes), url (needs codeUrl), or null (no 2FA). |
codeUrl | string | – | – | codeSource url: a public HTTPS endpoint the platform asks (signed POST) every 5 s while a wait lasts. Up to 2048 characters. |
codeTimeoutSeconds | integer | 300 | – | From 5 to 900. |
value | string | – | – | A secret's value. 1 to 8000 characters. |
description | string | – | – | Up to 500 characters. |
shell | boolean | false | – | |
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. |
More examples:
{ "name": "GITHUB_TOKEN", "type": "secret", "value": "ghp_…", "description": "CI bot", "scope": "shell"}curl -X POST https://api.boxline.dev/v1/credentials \ -H "x-api-key: $BOXLINE_API_KEY" \ -H "content-type: application/json" \ -d '{"name": "SHOP", "type": "password", "origins": ["https://shop.example.com"], "username": "ops@example.com", "password": "'"$SHOP_PASSWORD"'", "totpSecret": "'"$SHOP_2FA_KEY"'", "scope": "all"}'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst shop = await bx.credentials.create({ name: "SHOP", type: "password", origins: ["https://shop.example.com"], username: "ops@example.com", password: process.env.SHOP_PASSWORD!, totpSecret: process.env.SHOP_2FA_KEY, scope: "all",});console.log(shop.name, shop.username, shop.hasTotp); // never the password or the 2FA keyimport osfrom boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLshop = bx.credentials.create( "SHOP", "password", origins=["https://shop.example.com"], username="ops@example.com", password=os.environ["SHOP_PASSWORD"], totp_secret=os.environ["SHOP_2FA_KEY"], scope="all",)print(shop["name"], shop["username"], shop["hasTotp"]) # never the password or the 2FA key# Values are read from stdin (or a hidden prompt), never an argument.printf %s "$GITHUB_TOKEN" | boxline credentials set GITHUB_TOKEN --scope shell --description "CI bot"boxline credentials set SHOP --type password --username ops@example.com --origin https://shop.example.comResponses
201 Created
The credential (without its values; codeUrlSecret once when codeUrl was set).
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. |
| 403 Forbidden | project_suspended, organization_suspended, role_forbidden, forbidden, extension_denied, cross_site_request, console_login_required, impersonating, invite_email_mismatch, email_unconfirmed | Not allowed. |
| 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.