Credentials API reference
Store portal logins in the vault over three endpoints: create with a release scope, list field names only, revoke — read-back does not exist.
Last updated:
The vault holds portal logins so an agent can sign in without a secret ever entering a prompt. Its API surface is deliberately small — create, list, revoke — and asymmetric: what goes in never comes back out. Calls authenticate the standard way, an API key behind Bearer in the Authorization header.
/v1/credentials
Stores a credential and answers 201 with its record — field names, never values.
Create body
| Name | Type | Description |
|---|---|---|
name
required
|
string | A label, up to 120 characters. |
url
required
|
string | Defines the release scope: the registrable site this credential may ever be typed on, and nowhere else. |
fields
required
|
object | At least one `name: value` pair; values are sealed with your tenant key and released only inside a session, on the granted site, at the moment of typing. |
totpSeed
|
string | A TOTP seed; codes are generated server-side, so the seed never leaves the platform. |
nonSecretFields
|
string[] | Up to 16 field names you declare non-secret, such as a username. |
/v1/credentials
Lists your credentials as metadata only.
No read-back, by design
A listed credential shows id, name, grantUrl (note: the create body's url comes back under this name), the field names, hasTotp, nonSecretFields and the timestamps createdAt, lastUsedAt and revokedAt. There is no endpoint that returns a stored value, and none is planned: the planner works with opaque placeholders, and a placeholder without a vault grant is refused rather than typed literally.
/v1/credentials/:id
Revokes the credential — a revocation, not an erasure: the record keeps its `revokedAt`.
Note · Self-hosted without a key provider
On a self-hosted deployment the vault needs a key provider — OVHcloud KMS, or a local KEK outside production. Without one, these endpoints answer 503 `capacity_unavailable` naming the missing configuration.
Store a login, list the names
Creates a credential scoped to one portal and lists it back — names only.
Requires: api-key kek
BASE="https://browserberg.com"
AUTH="Authorization: Bearer $BROWSERBERG_API_KEY"
JSON="Content-Type: application/json"
# Create: the URL defines the only site this credential may ever be typed on.
curl -s -X POST "$BASE/v1/credentials" -H "$AUTH" -H "$JSON" -d '{
"name": "Example portal",
"url": "https://portal.example.com/login",
"fields": { "username": "buchhaltung@firma.example", "password": "not-a-real-password" },
"nonSecretFields": ["username"]
}' | python3 -m json.tool
# List: field NAMES only. There is no read-back endpoint, by design.
curl -s "$BASE/v1/credentials" -H "$AUTH" \
| python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)["credentials"], indent=2))'