Authority API

Authority management routes are operator-scoped. Tenant identity comes only from the authenticated context; no request body accepts an operator ID. Reads return safe metadata. Management writes require an owner or admin context and an Idempotency-Key header.

Read safe metadata

curl https://api.getstack.run/v1/authority/bindings \
  -H "Authorization: Bearer $STACK_TOKEN"

• GET /v1/authority/principals and /principals/:principalId
• GET /v1/authority/proofs and /proofs/:proofId?version=
• GET /v1/authority/bindings and /bindings/:bindingId?version=
• GET /v1/authority/bindings/:bindingId/approval-requests
• GET /v1/authority/receivers and /receivers/:receiverId
• GET /v1/authority/uses and /uses/:useId
• GET /v1/authority/presentations and /presentations/:presentationId

The authenticated Console uses the same reads through a stricter browser projection. It omits proof-source details, receiver identifiers, endpoints, keys, policies, request hashes, disclosure manifests, and any unknown fields.

Principals and proofs

• POST /v1/authority/principals - create an opaque person, organisation, or workload principal.
• POST /v1/authority/principals/:principalId/archive - stop future use without erasing evidence.
• POST /v1/authority/principals/:principalId/erase - revoke and erase through governance step-up.
• POST /v1/authority/proofs/import - submit provider-native evidence for registered-adapter verification. Evidence is not echoed.
• POST /v1/authority/proof-collection-sessions - start a provider-native collection ceremony.
• GET /v1/authority/proof-collection-sessions/:sessionId - read safe ceremony state.
• POST /v1/authority/proofs/:proofId/revoke - revoke a proof and cascade dependent authority.
• POST /v1/authority/proofs/:proofId/erase - destroy proof ciphertext after governance step-up.

Bindings and approvals

• POST /v1/authority/bindings - create an immutable binding version from verified proof references, exact agent and receiver, purpose, policies, scope, and validity.
• POST /v1/authority/bindings/:bindingId/approval-requests - create immutable activation, action, or presentation approval slots.
• POST /v1/authority/bindings/:bindingId/activate?version= - activate after proof, approval, profile, key, and status checks. Governance step-up applies.
• POST /v1/authority/bindings/:bindingId/delegate - create a strictly narrower child binding.
• POST /v1/authority/bindings/:bindingId/revoke - revoke this binding and its dependent chain.
• POST /v1/authority/bindings/:bindingId/erase - revoke and retain only a signed tombstone after governance step-up.

Passport issue attaches bindings with authority_binding_ids. STACK resolves the active version, exact agent, and current agent key before copying an opaque reference into the JWT. See Passports API.

Approval from the Console

An API client creates a short-lived request for one agent, connected system and job. STACK returns an approval URL. A signed-in owner or admin reviews those exact terms once, confirms their identity, and grants a reusable Authority for matching actions. Company sign-in can also verify the configured company-role claim. Stripe Identity verifies the person; the customer account records the company role under which they approve.

• POST /v1/authority/enterprise-oidc/requests - create the pending request and return its human approval URL. This route requires an owner or admin bearer context and rejects agent contexts.
• GET /v1/authority/enterprise-oidc/requests/:requestId - read pending, rejected or completed status without receiving identity-provider evidence.
• GET /v1/authority/enterprise-oidc/requests/:requestId/review - load the exact terms in a signed-in Console session.
• POST /v1/authority/enterprise-oidc/requests/:requestId/start - begin the selected company sign-in or Stripe Identity check for that request.
• POST /v1/authority/enterprise-oidc/requests/:requestId/complete - complete the identity check in the same signed-in browser and create the binding once.
• POST /v1/authority/enterprise-oidc/requests/:requestId/reject - decline the pending request without creating Authority.

Human approval decision

POST /v1/authority/approval-requests/:approvalId/decide

This route rejects Bearer authentication. It requires a signed-in dashboard cookie, the configured dashboard origin, an eligible owner or active standard/admin member, and an idempotency key. The body carries the same request ID, approve or reject decision, exact request hash, and a signed decision over that hash. Identity and eligibility are derived from the session, never from the body.

Receivers, keys, and profiles

• POST /v1/authority/receivers - register a native or proxy-bridge receiver.
• POST /v1/authority/receivers/:receiverId/verification-challenges and /verify - prove control of a native receiver.
• POST /v1/authority/receivers/:receiverId/keys - add a public asymmetric request, encryption, receipt, or mTLS key.
• POST /v1/authority/receivers/:receiverId/keys/:keyId/revoke - revoke a pinned receiver key.
• POST /v1/authority/profile-versions - create immutable proof, domain, or receiver profile JSON.
• POST /v1/authority/profile-versions/:profileId/activate - activate one profile kind after governance step-up.

Native receiver origins must be normalized public HTTPS origins. STACK does not follow request-supplied key URLs or accept private or symmetric JWK material.

Receiver-authenticated protocol

• POST /v1/authority/presentation-requests - submit the signed receiver request, agent proof of possession, write-only Passport, exact authority reference, action, hashes, and requested fact modes.
• GET /v1/authority/presentation-requests/:presentationId - read safe delivery state for the pinned receiver.
• POST /v1/authority/status-checks - check one exact live authority statement and normalized action.
• POST /v1/authority/presentations/:presentationId/receipts - submit a write-only receiver-signed transaction receipt.

These routes use short-lived receiver JWS authentication pinned to receiver ID, method, normalized path, body digest, audience, nonce, expiry, and registered key. They are not operator management routes.

Failure behavior

Unknown, stale, expired, suspended, revoked, replaced, erased, or unavailable required state denies before action or disclosure. Replay conflicts fail at the PostgreSQL uniqueness or compare-and-swap gate. Database, KMS, signing-key, or required live-status failure returns a retriable service error and performs no protected action.

See Authority concepts, Proxy mediation, and Missions.