The lanyard REST API, end to end.

Exchange an actor + password for a session token. The only endpoint that takes identity from the body; the password is verified against the policy's bcrypt hash. Unknown actor and wrong password return the same generic 401 (anti-enumberation).

Revokes the caller's own session. The token itself is the credential — no body, no path id. Subsequent calls with that token fail 401.

Report the caller's own identity and which managed resources they may view and manage. Scoped to the caller by construction — the actor comes from the token, never the request — so there is no way to ask this about someone else. manages is always a subset of views: management implies view, never the reverse, which is what makes a read-only auditor expressible. This is presentation input only; every other endpoint re-checks authority itself, so a tampered copy buys nothing but a menu item that 403s.

Request access to an entitlement for a duration. The policy engine runs first: auto_approve may return the grant already active; otherwise it returns pending, waiting on a human approve. A deny (duration over max_duration, requester not allowlisted where required) returns 403 — never 201 with a denied state. Fails closed.

List grants visible to the caller. Optional ?status= narrows to one lifecycle state; an unrecognized value is a 400 (not silently ignored). The usecase enforces per-caller visibility — a grant you may not see is absent, never redacted.

Inspect one grant. "Not found" and "not visible to you" are deliberately indistinguishable — both return 404, so the existence of a grant you can't see never leaks.

Approval progress

A chained grant also carries an approval object; a chainless one omits the key entirely rather than sending null. current_level is the index into levels awaiting a decision, and equals the number of levels once all are decided. Each level reports the roles that may satisfy it (any one is enough) and a status of approved, pending, or skipped_vacant — the last meaning no member of any of its roles could approve, so it was skipped upward. A decided level adds approver and decided_at, plus delegator when the approver acted on delegated authority: both names are recorded, so accountability is never laundered through a delegation.

Approve a pending grant. The approver must hold the approve verb on the entitlement, and cannot be the requester (no self-approval). On success the grant becomes active with activated_at and expires_at set. No request body.

End a grant early. Works on pending and active grants. The revoker must hold the revoke verb on the entitlement. A reason is optional but recommended for the audit trail. Terminal grants (expired/revoked) reject with 400.

Search the entitlements the caller may request, live from the connected providers. Scoped per caller: an entitlement the caller cannot see is absent, not marked forbidden — the catalog discloses the shape of the estate lanyard fronts, which is worth gating on its own. Cursor-paginated like /audit. Query params: ?q= to filter, ?provider= to narrow to one provider, ?cursor= and ?limit= to page.

total is the full match count, not the page size, and groups carries the per-provider counts a vendor-grouped catalog needs to render its collapsed list without fetching every page first.

The request-form templates: an entitlement pattern plus the parameters that fill its wildcards. This is what lets a console offer "request access to a repo" without the requester hand-writing a four-segment entitlement.

The values a template parameter can take, fetched live from the provider — the repositories an installation can see, for instance. Separate from the template itself because the shape is static config while the options change under it.

The merged chain view: entries provisioned from policy.yaml (read-only, provisioned:true) alongside those managed here. Each level is the list of roles that may satisfy it — [["team_lead"],["security","compliance"]] means "a team lead, then either security or compliance". Ordering is the control: level 2 cannot decide before level 1.

Create or replace the chain for one entitlement pattern. A level is admitted when at least one of its roles holds an approve permission overlapping the pattern; a level no role could ever satisfy is rejected rather than saved as a chain that can never complete.

Remove the chain for a pattern, passed as ?pattern=. Requests matching it then fall back to the next-most-specific chain, or to the policy default — never to "no approval needed" by accident.

The role catalog: each role's entitlement permissions, the resources it manages, and the resources it may only view. Reads are gated, not just writes — the binding graph discloses who holds admin, which is exactly what an attacker enumerates first.

Create a role. is_admin is a blanket grant over every managed resource and every verb — the finer-grained manages/views lists exist so it rarely has to be used.

Replace a role's definition wholesale. Not a patch: omitting permissions removes them, which is the safer default — a partial update that silently keeps an old grant is how privilege outlives the decision to remove it. The audit event records the before and after of every field.

Delete a role. Bindings to it go with it, so anyone who held authority only through this role loses it immediately.

The whole actor-to-role graph, one entry per actor.

The roles held by one actor. Distinct caller and target: asking about yourself and asking about someone else are different questions, and both are checked.

Bind an actor to a role. Idempotent — binding twice is not an error.

Unbind an actor from a role. Takes effect on the next authorization check, not at the next login — authority is read per request, so removal is immediate.

Delegate your own approval authority over a scope until an expiry. The delegator is always the caller — you cannot delegate authority you do not hold, and you cannot delegate on someone else's behalf. An approval made under a delegation records both the delegate and the delegator in the audit trail, so accountability is not laundered through it.

Delegations visible to the caller — those they granted and those they hold. Expired and revoked ones are returned too, with their end state, because "who could approve this last Tuesday" is an audit question.

End a delegation early. The revoker is recorded — a delegation is never revoked anonymously. Revoking one already revoked is a 400, not a silent success.

Register a provider integration. The config blob is validated by the provider's adapter (e.g. GitHub App fields); secrets inside it are env://NAME references resolved at use time, not raw values.

List registered integrations. Returns provider and created_at only — never config.

Revoke a registered integration. Keyed on the composite (provider, name), not on provider alone — one broker routinely fronts several accounts of the same vendor, and keying on provider would make removing one silently destroy the others. Revoking one that was never registered is a 404, not a silent success.

The registered backends. Only the address and its labels are returned — a secret manager record stores where to look, never what is found there.

Register a backend. Keyed by its own id rather than by provider, so several instances of one vendor — one per environment or account — coexist instead of overwriting each other.

Remove a backend. Integrations that resolved their credentials through it stop being able to, which surfaces as provider failures on the next sweep rather than as silent success.

Issue a single-use, expiring token authorizing exactly one identity to set its own password. Gated on credentials, deliberately distinct from bindings: binding a role decides what an identity may do, while enrolling bootstraps how it authenticates at all.

Redeem an enrollment token by setting a password. Unauthenticated by necessity — the whole point is that the identity has no credential yet. The token is single-use and expiring, and the password is hashed before it touches storage, so nobody else ever learns it.

Read the audit trail visible to the caller. Every request, approval, revoke, expiry, role change, and login outcome emits an immutable event answering who, what, when, where, how and why — plus the before-and-after of anything it changed. Events are returned newest-first and cursor-paginated: pass the next_cursor from one page as ?cursor= to get the next, and ?limit= to size it.

Recompute the audit trail's hash chain end to end and report whether it is intact. Each event is linked to its predecessor, so an event that was altered or removed after the fact breaks the chain at that point and broken_id names where. This is an operator action over the whole trail, which is why it needs audit authority while reading individual events only needs to be able to see them.

The reconciliation sweep's heartbeat, the grants it currently cannot reconcile, and recently resolved incidents. The sweep is what revokes access when a grant expires; if it stops, nothing else reclaims that access, and until this endpoint existed its only trace was a line on stderr.

Read last_run and open together. An empty open means "nothing is wrong" only when last_run is recent and fully_recorded; a null last_run means no sweep has ever completed, which is a different thing from a clean one.