Docs / API

Control-plane REST API

Two audiences: agents hit the broker endpoint with an end-user token; humans hit the admin surface with a verified session (or the dashboard does it for them). All admin routes are org-scoped and role-gated: viewer < admin < owner < superadmin.

The broker

POST /v1/credentials

POST /v1/credentials
Authorization: Bearer <end-user identity token>
X-Keyward-Agent: invoice-bot
X-Keyward-Environment: prod            # optional, default prod
X-Keyward-Agent-Assertion: <oidc jwt>  # required only for attested agents
X-Keyward-Delegation: <prior keyward credential>  # chain extension (replaces user token)

{ "provider": "stripe", "scope": "charges:read", "ttl": "5m" }

→ 200 { credential, token_type, provider, scope, expires_at, delegation }
→ 202 { status: "pending_approval", approval_id }   # policy effect require_approval

Denials are explicit and every one is audited: 401 invalid_user_token / invalid_delegation, 404 unknown_agent / unknown_provider, 403 agent_revoked / scope_not_allowed / policy_denied / agent_attestation_required / delegation_too_deep, 502 native_mint_failed.

Verification & health

Route	What
`GET /v1/jwks`	public signing keys — verify issued credentials without a shared secret
`GET /healthz`	liveness

Admin surface (session bearer, org-scoped)

Route	Role	What
`GET /v1/audit`	viewer	recent tied audit rows
`GET /v1/audit/export?format=json\|csv`	viewer	full export, up to 50k rows, page via since=
`POST /v1/audit/prune`	admin	delete rows older than { days }
`GET\|POST /v1/agents · /:id/revoke · /:id/restore`	admin	register (idempotent), revoke, restore
`GET\|POST /v1/secrets · /:provider/rotate`	admin	metadata only — plaintext never returned
`GET\|POST\|DELETE /v1/policies`	admin	deny-by-default rules: (agent?, provider?, scope?) → allow \| deny \| require_approval
`GET /v1/approvals · POST /:id/approve\|deny`	admin	human-in-the-loop queue for require_approval
`GET /v1/admins · POST /:subject/role`	owner	RBAC management
`GET /v1/usage · POST /v1/usage/report`	viewer / admin	plan, counts, monthly issuance; push to billing
`POST /v1/orgs/:id/kms`	superadmin	BYOK — set the org's customer-managed KMS key

Account & tenant auth

Route	What
`POST /auth/signup`	create a tenant: org + owner account, returns a 12h session token
`POST /auth/login`	password login; 401 totp_required when 2FA is enabled
`GET /auth/me`	current account, org, role, 2FA status
`POST /auth/2fa/setup · enable · disable`	TOTP enrollment (RFC 6238, QR)
`GET /auth/tenant?email=`	tenant SSO routing — returns the org's IdP connector if the email domain has one

Provisioning (enterprise)

SCIM 2.0 Users under /scim/v2/Users (Okta / Entra provisioning; static bearer via KEYWARD_SCIM_TOKEN, disabled when unset). Audit events stream in real time to a SIEM webhook when configured — see Self-hosting for the environment variables.