Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.

On this page

HTTP API

This page lists every endpoint of the Bouncer API, contract bouncer.v1, as the server implements it in Bouncer 0.5.7. The page footer identifies the source commit. It is generated from the contract files in the repository: contracts/openapi.yaml (the endpoints) and contracts/schemas/bouncer.v1.json (every object named below). Those files have the full field-by-field detail, and contracts/examples/ has an example of each object.

Most integrations don't need the API directly: the CLI and the MCP server speak it for you.

Conventions

  • Base path /v1. The server itself speaks plain HTTP, on 127.0.0.1:8080 by default (--listen); clients reach it over HTTPS through the reverse proxy in front of it. Bodies are JSON in UTF-8.
  • Credentials go in Authorization: Bearer: a requester key (brk_...) or a device token (bdt_...). Health and pairing need none. Never put a key in a URL.
  • Admin endpoints (/admin/v1) are served only on the server's local Unix socket, never over the network. bouncer-admin calls them.
  • Only a signed statement from a paired device approves. No credential on its own can.
  • IDs have several formats. Generated request IDs have a prefix and 26 lower-case characters, such as req_01jbx3k9m2p4q6r8s0t1v3w5y7; resource IDs and personal credential IDs use other formats. Treat them as opaque.
  • Times are UTC, RFC 3339, whole seconds: 2026-11-15T14:02:00Z.
  • Durations are objects: {"kind": "finite", "seconds": 900}, or {"kind": "always"}.
  • Unknown fields in a request body are refused. Clients should ignore unknown fields in responses, and treat unknown values as "something else".
  • Idempotency. Creating a request and fetching a token take an idempotency_key. Repeating a request with the same key and body returns the first request; a different body is 409 idempotency_conflict. Repeating a token fetch with the same key issues a new token and revokes the earlier one, so a retry never leaves two live tokens.
  • Long polling. GET /v1/requests/{request_id}?wait=N and GET /v1/events?wait=N wait up to N seconds (at most 60) for a change.
  • Secrets in transit. Four responses on the network side carry a secret, and are sent with Cache-Control: no-store: POST /v1/grants/{grant_id}/credentials (a short OpenBao token), POST /v1/resources/{resource_id}/view (the secret's values), POST /v1/credentials/{resource_id}/versions/{version}/view (an old version's values) and POST /v1/pair (the new device token). Three admin responses carry one too: POST /admin/v1/requesters and POST /admin/v1/requesters/{requester_id}/key (the requester's new key), and POST /admin/v1/pairing-codes (a one-time pairing code). These don't set no-store, but they only ever travel over the server's local Unix socket, never through a proxy or cache. Only four endpoints accept secret values: POST /v1/resources/{resource_id}/store, POST /v1/grants/{grant_id}/write, POST /v1/credentials/{resource_id}/lifecycle (a replacement) and POST /v1/personal-credentials. The server never logs any of these secrets. It keeps no copy of OpenBao tokens or secret values, and keeps requester keys, device tokens and pairing codes only as hashes.

Session

GET /v1/health

Is the server up, and which Bouncer is it.

Caller: none. Returns: Health.

Needs no credential. The app reads the instance ID here before pairing, because the pairing statement is addressed to it. The instance's flags say what this server supports: credential_types: true (0.5.0) means it accepts credential_type in personal create and rename bodies; older servers leave it out. device_reports: true means it takes device reports at POST /v1/devices/self/reports; an app doesn't report to a server without it. GET /v1/session carries the same instance. It is also the readiness check: while OpenBao is sealed, can't be reached or refuses the server's own login, it answers 503 with backend_sealed, backend_unreachable or backend_auth_failed and a Retry-After, and so does every other public call except the three that only take access away: a grant's revoke, a device's own revoke and a request's cancel. Those still work, and a revoke reports the tokens OpenBao couldn't revoke yet as revoke_failed; the server revokes them once OpenBao is back. The server stays up and issues nothing until OpenBao is ready again. The problem holds no address and no token. From 0.5.7, the database is also checked with a short SELECT 1 probe on a separate connection, cached for up to five seconds. If PostgreSQL is unavailable, every public call, including revoke and cancel, answers 503 database_unavailable with Retry-After: those calls need the database to commit their changes. The process stays up and recovers without a restart. In 0.5.6, a call that needs PostgreSQL and cannot reach it fails with 500 internal.

GET /v1/session

Who the caller is, and the server's time.

Caller: requester key, device token. Returns: Session.

The apps use server_time to show countdowns against the server's clock, not their own.

Requests

GET /v1/resources

The resources the caller may request, with each one's duration menu.

Caller: requester key, device token. Returns: ResourceList.

A device lists the resources its person may request through their own human requester. Searching and filtering only narrow that list: they read metadata (ID, name, description, folder), never a value, and a folder never makes a resource visible or requestable.

GET /v1/requests

List requests.

Caller: requester key, device token. Returns: RequestPage.

role=approver (devices only) lists requests the caller's person can decide: the inbox. role=requester lists the caller's own requests. Newest first.

POST /v1/requests

Ask for access.

Caller: requester key, device token. Body: CreateRequest. Returns: Request.

Files a request as the caller's requester. A device files it as its person's own human requester. The server checks the policy, works out the duration menu and the deadline, notifies the approvers, and returns the request as pending.

GET /v1/requests/{request_id}

One request.

Caller: requester key, device token. Returns: Request.

Visible to its requester and to its approvers' devices. With wait=N, the call is held for up to N seconds (at most 60) while the request is pending, and returns as soon as it changes. bouncer wait uses this.

POST /v1/requests/{request_id}/cancel

Withdraw a pending request.

Caller: requester key, device token. Returns: Request.

Only its requester can cancel it. The approvers' notifications are withdrawn.

Decisions

POST /v1/challenges

Get a single-use challenge to sign.

Caller: device token. Body: ChallengeRequest. Returns: Challenge.

Devices with an approval key only. A challenge is bound to this device and, for a decision, to the request and its revision. It lasts 2 minutes by default and is used up by the first statement that carries it, whatever the outcome.

POST /v1/requests/{request_id}/decision

Approve or deny, with a signed decision statement.

Caller: device token. Body: DecisionRequest. Returns: DecisionResult.

The server checks everything in contracts/README.md section 4 inside one transaction, then commits the decision and, on approval, the grant. Any failed check is logged as a rejected attempt, never as a vote, and the challenge is used up either way.

Grants

GET /v1/ssh/krl

The SSH revocation list (KRL) for destination hosts.

Caller: requester key. Returns: binary data.

An OpenSSH KRL, for sshd's RevokedKeys, signed by nothing and naming the SSH CA. It revokes, by key ID, every certificate of each ssh_host grant that was cut off while a certificate of it may still be live, and by serial each certificate a retry replaced. Entries drop out 5 minutes after the certificates they name have ended. The version goes up by one whenever the list changes. Only an active requester of kind host may fetch it; destinations do so on a timer (deploy/ssh-krl/) and install it with an atomic rename.

GET /v1/grants

List grants.

Caller: requester key, device token. Returns: GrantPage.

A requester sees its own grants. A device sees grants on the resources its person approves, plus its person's own. Newest first.

GET /v1/grants/{grant_id}

One grant.

Caller: requester key, device token. Returns: Grant.

POST /v1/grants/{grant_id}/credentials

Get a short OpenBao token for an active grant.

Caller: requester key. Body: CredentialRequest. Returns: Credential.

The grant's requester only. The server re-checks the grant, asks OpenBao for a token through the resource's token role, reads back its real lifetime, records the accessor, and returns it. The token lasts at most the resource's credential_ttl (5 minutes by default) and never past the grant's end.

POST /v1/grants/{grant_id}/write

Save the values for an approved store request.

Caller: requester key. Body: WriteSecretRequest. Returns: WriteResult.

The grant's requester only, for a grant whose actions are ["write"] (an approved store request). The body has one value for each field the request named, and no others. The server writes them into the resource's one secret, then ends the grant: each store approval is used once, whatever the outcome.

POST /v1/grants/{grant_id}/revoke

End a grant now.

Caller: requester key, device token. Returns: RevokeResult.

Allowed for the grant's requester, and for any active device of a person who approves the resource or owns the requester. Not signed: revoking only takes access away.

Devices

GET /v1/devices

The caller's person's devices.

Caller: device token. Returns: DeviceList.

PUT /v1/devices/self/push-route

Register where to send this device's pushes.

Caller: device token. Body: PushRoute. Returns: nothing (204).

Routing data only; it proves nothing. Sent on every app start. Only fcm is accepted in this version; any other kind is refused with 422 invalid_body.

POST /v1/devices/self/revoke

Revoke the authenticated device.

Caller: device token. Body: an empty object, {}. Returns: Device.

Needs only this device's bearer token, without a signed statement. Accepts no query parameters or target fields. Send no body or {}. The device, its unused challenges and the standing grants it approved are cut off together. Its time-limited grants stay active until they end. Other devices and grants they approved are unaffected.

POST /v1/devices/self/reports

Record what only the device saw, in the approval log.

Caller: device token. Body: DeviceReportRequest. Returns: DeviceReportResult.

A paired device reports, with its own token, a screenshot or screen recording while Bouncer showed a protected screen, a copy of a value it had just viewed, or a failure to keep its window out of capture. Each report becomes one approval log entry of a reported_* kind, with the report in the entry's report. These are the device's word: the server can't verify them, and a missing report proves nothing.

POST /v1/devices/self/approval-key

Enrol a Windows Hello passkey as this Windows device's approval key.

Caller: device token. Body: ApprovalKeyRequest. Returns: Device.

A Windows device, paired without a key, proves it holds a new passkey by signing an approval_key statement as a WebAuthn assertion with user verification. Needs pairing.allow_webauthn_keys. The key is labelled platform-sw-uv: it can always deny, and approves any resource that doesn't set require_hardware_uv (or, from 0.5.7, require_hardware_key). From 0.5.7, the body may also carry the passkey's registration: with a tpm attestation that verifies to a pinned root, the key is recorded as attested and can meet require_hardware_key too; otherwise it enrols unattested while verified evidence is optional. In the current source (not yet released), pairing.require_verified_approval_keys (default false) instead requires verified evidence at installation and whenever a key signs. Keyless Windows bootstrap remains available. Device.key_proof adds status, evidence_kind and nullable checked_at; neither a declared platform nor assurance alone establishes proof. A configured requirement fails with 422 assurance_not_accepted and re-enrollment/operator-review guidance. A registration that isn't exactly its two strings is invalid_body; 0.5.6 and earlier refuse the field. A device that already has a key is refused with 403; to change it, sign out and pair again.

PUT /v1/devices/self/settings

Turn approval from notifications on or off, with a signed statement.

Caller: device token. Body: DeviceSettingsRequest. Returns: Device.

POST /v1/resources/{resource_id}/view

View a stored secret's value on this device, with a signed statement.

Caller: device token. Body: SecretViewRequest. Returns: SecretViewResult.

Only for a resource whose view setting isn't off: under grant_holder, for a person whose own human requester holds an active read grant for it (never an agent's); under approver (the older allow_device_view), for its approvers. Only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted. The statement carries a secret_view challenge, so it's used once. The answer is sent with Cache-Control no-store, and the value is never stored, logged or pushed. Each view is logged as secret_viewed, and each refusal as secret_view_refused.

POST /v1/resources/{resource_id}/store

Save values into a stored secret from this device, with a signed statement.

Caller: device token. Body: SecretStoreRequest. Returns: SecretStoreResult.

A one-shot, self-approved store request: the person is both requester and approver. Only for a resource with allow_write and self_approval, only for its approvers, and only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted, with the user verification the key enrolled with. The statement names the fields (never the values) and carries a secret_view challenge, so it's used once. The values are merged into the secret (other fields kept), never stored, logged or echoed. Each save is logged as secret_written, and each refusal as secret_write_failed with the reason.

GET /v1/credentials/{resource_id}/history

A credential's versions, states, dates and actors, without values.

Caller: device token. Returns: CredentialHistory.

For a config resource or personal credential with lifecycle on. Paired devices only (never requester keys), for a person who may see the credential: a personal credential's owner and the people it's shared with; a config resource's approvers. Built from OpenBao's version metadata (never values) and Bouncer's own records, newest first. A version OpenBao removed for good under max_versions keeps its line, as pruned. can_change and can_view_old say what this person may do.

POST /v1/credentials/{resource_id}/lifecycle

Expire, schedule or clear an expiry, or replace a credential's current version.

Caller: device token. Body: CredentialLifecycleRequest. Returns: CredentialLifecycleResult.

A signed credential_lifecycle statement over a single-use secret_view challenge, from a device whose approval key isn't kept in software on a phone, with the user verification it enrolled with. From 0.5.7, it needs a key that checks the person on each use (fingerprint, face or Windows Hello); an Android key that only needs the phone unlocked is refused, and the credential's require_hardware_uv and require_hardware_key settings apply. version must still be the current version, or it's version_conflict and nothing changes. Expiring deletes nothing: the value stays in OpenBao's version history, and every live token and unused wrapped hand-out Bouncer issued for it is revoked. A replacement is a KV version 2 patch with cas, a new version at the same path. While retention is held, one that would make OpenBao remove an old value for good is refused (prune_not_confirmed), and so is any statement with a prune_version. Personal credentials: Editors and up. Config resources: approvers; a replacement also needs allow_write and self-approval. Expiring or replacing a token issued by another system doesn't revoke it there. Every change is logged; every refusal is logged as credential_lifecycle_refused.

POST /v1/credentials/{resource_id}/versions/{version}/view

See an old version's value once, as its own authorised and logged operation.

Caller: device token. Body: CredentialLifecycleRequest. Returns: CredentialVersionView.

Never part of the history listing, and never for requester keys, agents, the CLI or MCP. A signed credential_lifecycle statement with op view_version naming the version. From 0.5.7, it needs a key that checks the person on each use (fingerprint, face or Windows Hello), and the credential's require_hardware_uv and require_hardware_key settings apply. 0.5.6 accepts any approval key that is not software-held on a phone, presence-only or synced, including an Android key that only needs the phone unlocked. Only a personal credential's owner, and a config resource's approvers where its view setting is on. Not the current version (use the resource's view). Logged as credential_version_viewed.

POST /v1/pair/preview

Check a pairing code before using it.

Caller: none. Body: PairPreviewRequest. Returns: PairPreview.

No bearer credential: the pairing code is the credential. Returns who the code pairs as and which Bouncer, so the app can show "As {person}" on the "Name this phone" screen. It doesn't use the code up. Wrong codes count towards the same rate limit as POST /v1/pair.

POST /v1/pair

Pair a device with a one-time code from bouncer-admin.

Caller: none. Body: PairRequest. Returns: PairResult.

No bearer credential: the pairing code is the credential. It works once. A device with an approval key (Android) sends a signed pairing statement as proof; a device without one (a Windows PC) sends null. Pairing adds a device_paired event for the person's other devices.

Personal credentials

GET /v1/personal-credentials

The personal credentials this person owns, or that are shared with them.

Caller: device token. Returns: PersonalCredentialList.

Metadata only, never a value. mine is what the caller owns; shared is what's shared with them now, through a person or group assignment, resolved by the config loaded now. A credential the caller has no access to isn't listed. Managers and the owner also see its assignments. From 0.5.7, responses add shared_by (the recorded human who last changed the selected assignment) and access_sources (only assignments matching this viewer now). Each actor is omitted unless they are the owner or the caller is an owner/Manager. Unchanged assignments retain their original actor and timestamp. 0.5.6 and earlier omit these fields; ownership is not a fallback actor. These metadata fields do not change permissions or approval mode. A disabled credential stays listed, with status disabled, for its owner (in mine) and its Managers (in shared), so the owner can re-enable or delete it; nobody else sees it, and nobody can use it.

POST /v1/personal-credentials

Create a personal credential from this device, with a signed statement.

Caller: device token. Body: PersonalCreateRequest. Returns: PersonalCredential.

The statement (op create) names the namespace, name, folder, field names, access mode and assignments, never the values, and carries a secret_view challenge, so it's used once. Only from a device whose approval key is not software-held on a phone (platform-sw-unlocked), presence-only or a synced passkey; Windows Hello (platform-sw-uv) is accepted, with fresh user verification, and only for a person the namespace lets create there, within its ceilings (field names and count, how many each owner may keep, whether reveal and Always approved are allowed). The values go once to OpenBao at <prefix>/<owner>/<id> and are never stored, logged or echoed. Private unless the statement shares it. Logged as sharing_changed, and each refusal as sharing_refused with the reason.

PUT /v1/personal-credentials/{credential_id}/sharing

Replace a personal credential's assignments and access mode, with a signed statement.

Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.

Op share. The owner may set anything within the namespace's ceilings, and signing the mode again ends a suspension of Always approved and starts its review over. A Manager may share with Viewers and Editors up to what they have themselves, and can't change the mode or Managers. Grants the new sharing no longer allows end at once, and their tokens are revoked.

POST /v1/personal-credentials/{credential_id}/disable

Disable a personal credential, with a signed statement (owner only).

Caller: device token. Body: PersonalChangeRequest. Returns: an object with id, status.

Op disable. Nobody can use it any more; its grants end and their tokens are revoked. A value already revealed can't be recalled.

POST /v1/personal-credentials/{credential_id}/enable

Re-enable a disabled personal credential, with a signed statement (owner only).

Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.

Op enable. Only for a disabled credential (an active one is forbidden). Its sharing and mode are as they were, so the summary the app shows before the signature must name them. The grants that disabling ended stay ended; new requests follow the mode.

POST /v1/personal-credentials/{credential_id}/rename

Rename or move a personal credential, with a signed statement (owner only).

Caller: device token. Body: PersonalChangeRequest. Returns: PersonalCredential.

Op rename, for an active credential. The statement names the new display name, kept exactly as typed, and folder (null is no folder). The ID, the OpenBao path, the sharing, mode, grants and history don't change, and no grant is suspended: a name and folder aren't policy. Refused with invalid_body when the owner already has a live credential of that name, ignoring case, in that folder. Anyone but the owner gets not_found.

DELETE /v1/personal-credentials/{credential_id}

Delete a personal credential, with a signed statement (owner only).

Caller: device token. Body: PersonalChangeRequest. Returns: an object with id, status.

Op delete, sent as the body of the DELETE, for an active or a disabled credential. As disable, and the credential is gone from every list. The value stays in OpenBao until the operator deletes it: Bouncer's policy has no delete there.

Events

GET /v1/events

Follow events for this device.

Caller: device token. Returns: EventPage.

Returns the events after the cursor, oldest first. Without after, it starts at the device's pairing. The server keeps events for at least 7 days; a cursor older than that returns every event still kept. With wait=N, the call is held for up to N seconds (at most 60) until there's at least one. The Windows app and the Android app in the foreground use this; pushes only carry an event's ID.

GET /v1/events/{event_id}

The event a push pointed to.

Caller: device token. Returns: Event.

Log

GET /v1/log

The approval log.

Caller: device token. Returns: LogPage.

Entries about the resources the caller's person approves, newest first. Entries of the reported_* kinds were reported by a device, not verified by the server (see POST /v1/devices/self/reports). A kind this server doesn't know is refused with invalid_body. Entries of kinds the client doesn't know are shown generically.

Admin

POST /admin/v1/pairing-codes

bouncer-admin device pair.

Caller: admin socket. Body: AdminPairingCodeRequest. Returns: AdminPairingCode.

GET /admin/v1/devices

bouncer-admin device list.

Caller: admin socket. Returns: DeviceList.

POST /admin/v1/devices/{device_id}/revoke

bouncer-admin device revoke.

Caller: admin socket. Returns: Device.

The device can no longer sign in, decide or see anything. Its pending challenges are void. The standing (Always) grants it approved are revoked with their tokens; the time-limited grants it approved stay active until they end. When this call revoked the device, the answer's revocation says what it ended and what it left, including any downstream credentials now due rotation. A device that was already revoked is answered as it stands, without revocation.

GET /admin/v1/requesters

bouncer-admin requester list.

Caller: admin socket. Returns: RequesterList.

POST /admin/v1/requesters

bouncer-admin requester add.

Caller: admin socket. Body: AdminRequesterCreate. Returns: RequesterWithKey.

Creates a requester and its first key. The key is shown once.

POST /admin/v1/requesters/{requester_id}/key

bouncer-admin requester rotate-key.

Caller: admin socket. Returns: RequesterWithKey.

Issues a new key and makes the old one stop working at once. The new key is shown once. A new key is a re-enrolment: the requester's standing grants are suspended (grant_suspended in the log) and need a fresh approval. Its time-limited grants stay until they end.

POST /admin/v1/requesters/{requester_id}/disable

bouncer-admin requester disable.

Caller: admin socket. Returns: Requester.

The key stops working, pending requests are cancelled, and active grants are revoked.

POST /admin/v1/revoke-all

bouncer-admin revoke --all (the kill switch).

Caller: admin socket. Returns: KillSwitchReport.

Ends every grant, cancels every pending request and revokes every issued token. The cutoff commits before anything else.

POST /admin/v1/config/reload

bouncer-admin config reload.

Caller: admin socket. Returns: ConfigReport.

Loads the config file again. An invalid file is refused and the old one stays loaded. Standing grants on a resource whose policy changed (a new resource_revision), or that left the file, are suspended. A change that loosens policy (a longer maximum, Always or self-approval newly allowed, more requesters, approvers or secrets, a weaker key requirement, or looser pairing) writes a policy_loosened log entry saying what loosened, and a policy_loosened event for the approvers' devices.

GET /admin/v1/log/export

bouncer-admin log export.

Caller: admin socket. Returns: LogExport.

The whole approval log, oldest first, in pages, for the operator to keep or ship to syslog or a SIEM. Ordinary entries keep the LogEntry shape. From 0.5.7, admin-only token_issued and backend_revoke entries add token_audit: issuance ID, issuance-time role (null for wrapped KV reads or older issuances), full non-secret accessor, and backend revoke outcome (null on issuance). The entry names the grant and time. The full accessor can be passed to sys/audit-hash on the relevant OpenBao audit device for an exact HMAC match. It cannot read credentials, but can look up or revoke a token. These records are excluded from device logs. Existing records are not backfilled; local expiry without a backend call creates no backend revoke record. Decision statements, signatures and secret values aren't included. Ask again with after set to the last page's cursor for the next page, or later for what's new. The cursor never passes an entry that's still being written. since and until pick a time window; until is excluded.

GET /admin/v1/ssh/krl

The SSH revocation list, for destinations.

Caller: admin socket. Returns: binary data.

The same KRL as GET /v1/ssh/krl, for a script on the server's own machine (deploy/ssh-krl/). 404 when the server has no SSH signer.

GET /admin/v1/downstream

bouncer-admin downstream list.

Caller: admin socket. Returns: DownstreamList.

Every resource whose value is a credential issued by another system, and whether it needs rotating there. Bouncer never calls that system.

POST /admin/v1/downstream/{resource_id}/rotated

bouncer-admin downstream rotated.

Caller: admin socket. Returns: Downstream.

Records that the admin rotated the resource's downstream credential at its system and updated the KV secret. Clears rotation_due and exposed_since; a value released after this counts again. Bouncer doesn't check the rotation. Writes a downstream_rotated log entry.

POST /admin/v1/grants/{grant_id}/review

bouncer-admin grant review.

Caller: admin socket. Returns: Grant.

Re-confirms an active standing grant's review, so it isn't suspended when review_due_at comes. The next review is due a full cadence (durations.always_review, 90 days by default) from now. Writes a review_confirmed log entry. A week before a review is due (or half the cadence, if that's shorter) the server writes review_due and tells the approvers' devices. A suspended grant can't be re-confirmed: the requester files a new request.

POST /admin/v1/personal-credentials/{id}/suspend

bouncer-admin personal suspend.

Caller: admin socket. Returns: an object with credentials, grants_ended.

Suspends Always approved on one personal credential: its grants that came from Always approved end and their tokens are revoked, and requests wait for approval until the owner signs the mode again. Logged as sharing_changed by the admin. A credential that isn't on Always approved, or is already suspended, is left as it is.

POST /admin/v1/personal-namespaces/{namespace}/suspend

bouncer-admin personal suspend --namespace.

Caller: admin socket. Returns: an object with credentials, grants_ended.

The same, for every active personal credential in the namespace.

POST /admin/v1/personal-credentials/{id}/freeze

bouncer-admin personal freeze.

Caller: admin socket. Returns: an object with credentials, grants_ended.

Freezes one personal credential: nobody can use it until it's reassigned, and all its grants end and their tokens are revoked. Use it before rolling back the server (migration 0012).

POST /admin/v1/personal-namespaces/{namespace}/freeze

bouncer-admin personal freeze --namespace.

Caller: admin socket. Returns: an object with credentials, grants_ended.

The same, for every active personal credential in the namespace.

POST /admin/v1/personal-credentials/{id}/reassign

bouncer-admin personal reassign.

Caller: admin socket. Body: an object with owner. Returns: an object with credentials, grants_ended.

Gives a frozen personal credential, or one whose owner left the config file, to another person ({"owner": "<person ID>"}), within the namespace's per-owner limit, so nothing is orphaned. It's active again with its assignments as they were, but Always approved stays suspended until the new owner signs the mode: an operator never chooses it for them. 400 (invalid_body) if the owner isn't a person, the namespace is gone, or the credential isn't frozen.

Errors

Errors are application/problem+json (RFC 9457) with a machine-readable code. A client that gets a code it doesn't know treats it by its HTTP status.

CodeHTTPMeaning
unauthenticated401No credential, or not a valid one
forbidden403Valid credential, but not allowed to do this
not_found404No such object, or not visible to this caller
invalid_body400The body doesn't match the schema
idempotency_conflict409Same idempotency key, different body
rate_limited429Too many requests; see Retry-After
requester_disabled403This requester is disabled
device_revoked403This device is revoked
not_requestable403This requester may not ask for this resource
duration_not_permitted422The duration isn't allowed for this resource. Never clamped
reason_invalid422The reason is empty, too long, or has control characters
not_an_approver403This person doesn't approve this resource
self_approval_not_allowed403This resource needs a different approver
channel_not_permitted422Notification approval isn't allowed here, isn't opted in on this device, or the duration differs from the requested one
confirmation_missing422Longer than requested without longer_than_requested, or the confirmation was given when it wasn't longer; or the matching code is missing or different
request_not_pending409The request was already decided, expired or cancelled
revision_mismatch409The request changed since the device fetched it
scope_mismatch422The statement's scope hash doesn't match the request
audience_mismatch422The statement is for another Bouncer
challenge_invalid422The challenge is unknown, used, expired, or for another device or request
statement_not_canonical422The statement bytes aren't canonical JSON
statement_invalid422The statement isn't base64url, isn't the right kind, or has fields the contract doesn't define
signature_invalid422The signature doesn't verify against this device's key
unsupported_signature_format422A signature format the server doesn't accept yet
key_mismatch422The statement's device, key ID or epoch isn't this device's current one, or its approver or assurance isn't this device's
assurance_not_accepted422The key's assurance or user verification doesn't meet the resource's policy
grant_not_active409The grant has expired, been revoked or been suspended
issuance_failed502Bouncer couldn't release a credential. The detail says whether a token may have been issued
write_failed502OpenBao didn't save a store request's values. The grant is used up anyway; file a new request
view_off403The resource doesn't allow viewing its value on a device
no_grant403A device view needs an active read grant held by one of this person's own human requesters; an agent's grant never counts
grant_expired403The person's grant for this resource has ended or been suspended
grant_revoked403The person's grant for this resource was revoked
store_only_grant403The person's only grant is a store request's, which saves values and never reads them
wrong_person403The active grant for this resource is another person's
not_found_in_backend404OpenBao has no value at the resource's path yet
credential_expired409The credential's current version has expired; nothing is issued, handed out or shown until a replacement is saved, and never an older version instead
version_conflict409The lifecycle operation named a version that is no longer current; nothing was changed
prune_not_confirmed409A write would make OpenBao remove an old version's value for good, which Bouncer never does while retention is held; an operator has to raise max_versions first
lifecycle_off403The credential has no version history (lifecycle is off)
pairing_code_invalid422The pairing code is unknown, used or expired
proof_required422This platform pairs with an approval key, so a pairing proof is required
config_invalid422The config file was refused; the old one stays loaded
backend_sealed503The server is running, but OpenBao, which it issues credentials from, is sealed. An operator must unseal it. An outage, not a refusal. Comes with Retry-After, on every call including GET /v1/health
backend_unreachable503The server is running, but can't reach OpenBao. An outage, not a refusal. Comes with Retry-After
backend_auth_failed503The server is running, but OpenBao refused the server's own login. An operator must fix it. An outage, not a refusal of the caller's credential. Comes with Retry-After
database_unavailable503The server is running, but PostgreSQL is unavailable. Comes with Retry-After; no credentials are issued and the server stays up and checks for recovery. From 0.5.7; 0.5.6 does not send this code.
resource_not_provisioned503This resource's kit token role or policy is missing or unsuitable. Comes with Retry-After; requests and issuance for it are blocked while other resources and health continue to serve. A metadata 403 with a live login instead means upgrade_needed, not a proven missing role or policy. From 0.5.7; 0.5.6 does not send this code.
internal500Something went wrong on the server

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).