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
- Conventions
- Session
- GET /v1/health
- GET /v1/session
- Requests
- GET /v1/resources
- GET /v1/requests
- POST /v1/requests
- GET /v1/requests/{request_id}
- POST /v1/requests/{request_id}/cancel
- Decisions
- POST /v1/challenges
- POST /v1/requests/{request_id}/decision
- Grants
- GET /v1/ssh/krl
- GET /v1/grants
- GET /v1/grants/{grant_id}
- POST /v1/grants/{grant_id}/credentials
- POST /v1/grants/{grant_id}/write
- POST /v1/grants/{grant_id}/revoke
- Devices
- GET /v1/devices
- PUT /v1/devices/self/push-route
- POST /v1/devices/self/revoke
- POST /v1/devices/self/reports
- POST /v1/devices/self/approval-key
- PUT /v1/devices/self/settings
- POST /v1/resources/{resource_id}/view
- POST /v1/resources/{resource_id}/store
- GET /v1/credentials/{resource_id}/history
- POST /v1/credentials/{resource_id}/lifecycle
- POST /v1/credentials/{resource_id}/versions/{version}/view
- POST /v1/pair/preview
- POST /v1/pair
- Personal credentials
- GET /v1/personal-credentials
- POST /v1/personal-credentials
- PUT /v1/personal-credentials/{credential_id}/sharing
- POST /v1/personal-credentials/{credential_id}/disable
- POST /v1/personal-credentials/{credential_id}/enable
- POST /v1/personal-credentials/{credential_id}/rename
- DELETE /v1/personal-credentials/{credential_id}
- Events
- GET /v1/events
- GET /v1/events/{event_id}
- Log
- GET /v1/log
- Admin
- POST /admin/v1/pairing-codes
- GET /admin/v1/devices
- POST /admin/v1/devices/{device_id}/revoke
- GET /admin/v1/requesters
- POST /admin/v1/requesters
- POST /admin/v1/requesters/{requester_id}/key
- POST /admin/v1/requesters/{requester_id}/disable
- POST /admin/v1/revoke-all
- POST /admin/v1/config/reload
- GET /admin/v1/log/export
- GET /admin/v1/ssh/krl
- GET /admin/v1/downstream
- POST /admin/v1/downstream/{resource_id}/rotated
- POST /admin/v1/grants/{grant_id}/review
- POST /admin/v1/personal-credentials/{id}/suspend
- POST /admin/v1/personal-namespaces/{namespace}/suspend
- POST /admin/v1/personal-credentials/{id}/freeze
- POST /admin/v1/personal-namespaces/{namespace}/freeze
- POST /admin/v1/personal-credentials/{id}/reassign
- Errors
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-admincalls 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 is409 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=NandGET /v1/events?wait=Nwait up toNseconds (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) andPOST /v1/pair(the new device token). Three admin responses carry one too:POST /admin/v1/requestersandPOST /admin/v1/requesters/{requester_id}/key(the requester's new key), andPOST /admin/v1/pairing-codes(a one-time pairing code). These don't setno-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) andPOST /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.
| Code | HTTP | Meaning |
|---|---|---|
unauthenticated | 401 | No credential, or not a valid one |
forbidden | 403 | Valid credential, but not allowed to do this |
not_found | 404 | No such object, or not visible to this caller |
invalid_body | 400 | The body doesn't match the schema |
idempotency_conflict | 409 | Same idempotency key, different body |
rate_limited | 429 | Too many requests; see Retry-After |
requester_disabled | 403 | This requester is disabled |
device_revoked | 403 | This device is revoked |
not_requestable | 403 | This requester may not ask for this resource |
duration_not_permitted | 422 | The duration isn't allowed for this resource. Never clamped |
reason_invalid | 422 | The reason is empty, too long, or has control characters |
not_an_approver | 403 | This person doesn't approve this resource |
self_approval_not_allowed | 403 | This resource needs a different approver |
channel_not_permitted | 422 | Notification approval isn't allowed here, isn't opted in on this device, or the duration differs from the requested one |
confirmation_missing | 422 | Longer 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_pending | 409 | The request was already decided, expired or cancelled |
revision_mismatch | 409 | The request changed since the device fetched it |
scope_mismatch | 422 | The statement's scope hash doesn't match the request |
audience_mismatch | 422 | The statement is for another Bouncer |
challenge_invalid | 422 | The challenge is unknown, used, expired, or for another device or request |
statement_not_canonical | 422 | The statement bytes aren't canonical JSON |
statement_invalid | 422 | The statement isn't base64url, isn't the right kind, or has fields the contract doesn't define |
signature_invalid | 422 | The signature doesn't verify against this device's key |
unsupported_signature_format | 422 | A signature format the server doesn't accept yet |
key_mismatch | 422 | The 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_accepted | 422 | The key's assurance or user verification doesn't meet the resource's policy |
grant_not_active | 409 | The grant has expired, been revoked or been suspended |
issuance_failed | 502 | Bouncer couldn't release a credential. The detail says whether a token may have been issued |
write_failed | 502 | OpenBao didn't save a store request's values. The grant is used up anyway; file a new request |
view_off | 403 | The resource doesn't allow viewing its value on a device |
no_grant | 403 | A device view needs an active read grant held by one of this person's own human requesters; an agent's grant never counts |
grant_expired | 403 | The person's grant for this resource has ended or been suspended |
grant_revoked | 403 | The person's grant for this resource was revoked |
store_only_grant | 403 | The person's only grant is a store request's, which saves values and never reads them |
wrong_person | 403 | The active grant for this resource is another person's |
not_found_in_backend | 404 | OpenBao has no value at the resource's path yet |
credential_expired | 409 | The 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_conflict | 409 | The lifecycle operation named a version that is no longer current; nothing was changed |
prune_not_confirmed | 409 | A 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_off | 403 | The credential has no version history (lifecycle is off) |
pairing_code_invalid | 422 | The pairing code is unknown, used or expired |
proof_required | 422 | This platform pairs with an approval key, so a pairing proof is required |
config_invalid | 422 | The config file was refused; the old one stays loaded |
backend_sealed | 503 | The 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_unreachable | 503 | The server is running, but can't reach OpenBao. An outage, not a refusal. Comes with Retry-After |
backend_auth_failed | 503 | The 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_unavailable | 503 | The 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_provisioned | 503 | This 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. |
internal | 500 | Something went wrong on the server |