API Reference

All REST routes under /v1/ require Authorization: Bearer <token> except /v1/auth/* and /health.

Health and metadata#

MethodPathDescription
GET/healthHealth check. Returns { status, version }.
GET/Web UI.
GET/v1/configServer config (non-sensitive values).

Authentication#

MethodPathDescription
POST/v1/auth/loginUser login (username + password → JWT).
POST/v1/auth/login/totpExchange pre-auth token + TOTP code for a full JWT.
GET/v1/auth/sso/statusPublic. Returns {enabled} so the unauth login page can decide whether to show the SSO button.
GET/v1/auth/sso/startPublic. Mints state+nonce+PKCE, redirects (302) to the IdP authorize URL.
GET/v1/auth/sso/callbackPublic. OIDC redirect target. Verifies the ID token, links by IdP-verified email, and 302s to /#sso=<jwt>.
POST/v1/auth/approle/loginExchange role_id + secret_id for a JWT.
GET/v1/auth/approleList AppRoles (admin).
POST/v1/auth/approleCreate AppRole (admin).
PUT/v1/auth/approle/:roleIdUpdate AppRole (admin).
DELETE/v1/auth/approle/:roleIdDelete AppRole (admin).
GET/v1/auth/usersList users (admin).
POST/v1/auth/usersCreate user (admin).
PUT/v1/auth/users/:usernameUpdate user (admin).
DELETE/v1/auth/users/:usernameDelete user (admin).

One-time bootstrap tokens that hand an agent durable AppRole credentials without secrets ever entering chat.

MethodPathDescription
POST/v1/onboardCreate an onboarding link for an AppRole (admin). Returns { token, url, expires_at }.
GET/v1/onboardList active onboarding links (admin).
GET/v1/onboard/:tokenFetch the rendered markdown bootstrap document (unauthenticated, idempotent until exchange).
POST/v1/onboard/:token/exchangeOne-shot exchange: consumes the token, returns { token (JWT), role_id, secret_id, base_url, mcp_url, role_display_name, policies, expires_in }.
DELETE/v1/onboard/:tokenRevoke an unused onboarding link (admin).

TOTP self-service#

MethodPathDescription
GET/v1/me/totpGet TOTP status.
POST/v1/me/totp/setupBegin TOTP enrollment (returns QR code).
POST/v1/me/totp/verifyConfirm TOTP setup, activate, return recovery codes.
DELETE/v1/me/totpDisable TOTP (requires password).
POST/v1/me/totp/recovery-codes/regenerateRegenerate recovery codes.

Secrets#

MethodPathDescription
GET/v1/secrets?prefix=List secrets accessible to the caller.
GET/v1/secrets/:pathGet secret metadata.
GET/v1/secrets/:path/valueGet secret value.
POST/v1/secrets/:pathCreate or update secret.
DELETE/v1/secrets/:pathDelete secret.

Leases#

MethodPathDescription
POST/v1/lease/:pathCheck out a lease (returns lease + value).
GET/v1/leaseList active leases.
DELETE/v1/lease/:leaseIdRevoke a lease.

Proxy#

MethodPathDescription
POST/v1/proxyForward an HTTP request with secret injection.

Dynamic secrets#

MethodPathDescription
GET/v1/dynamicList dynamic secret configs (admin).
POST/v1/dynamicCreate or update config (admin).
GET/v1/dynamic/:pathGet config detail (admin, redacted).
DELETE/v1/dynamic/:pathDelete config and revoke all leases (admin).
POST/v1/dynamic/:path/checkoutCreate a temp credential.
POST/v1/dynamic/:path/validateTest provider connection (admin).
GET/v1/dynamic/:path/leasesList active dynamic leases (admin).
DELETE/v1/dynamic/lease/:leaseIdRevoke a dynamic lease.
POST/v1/dynamic/generate-ca-keypairGenerate ed25519 CA keypair (admin).
GET/v1/dynamic/:path/ca-pubkeyGet CA public key for an existing config (admin).

Patterns#

MethodPathDescription
GET/v1/patternsQuery learned patterns (admin).
GET/v1/patterns/:idGet a pattern by ID (admin).
POST/v1/patterns/:id/pinPin or unpin a pattern (admin).
DELETE/v1/patterns/:idDelete a pattern (admin).

Policies#

MethodPathDescription
GET/v1/policyList policies (admin).
GET/v1/policy/:nameGet policy detail (admin).
POST/v1/policyCreate policy (admin).
PUT/v1/policy/:nameUpdate policy (admin).
DELETE/v1/policy/:nameDelete policy (admin, DB-backed only).
POST/v1/policy/reloadReload policies from disk (admin).

Audit#

MethodPathDescription
GET/v1/audit?...Query audit log.
GET/v1/audit/retentionGet retention policy (admin).
POST/v1/audit/retentionSet retention policy (admin).
POST/v1/audit/purgeManually purge old entries (admin).

Scrubbing#

MethodPathDescription
POST/v1/scrubScrub credentials from text.
POST/v1/scrub/checkQuick boolean credential check.

Admin#

MethodPathDescription
POST/v1/admin/rotate-keyRotate master key, re-wrap all DEKs (admin).
GET/v1/settings/ssoGet SSO config (admin).
POST/v1/settings/ssoUpdate SSO config (admin).
GET/v1/settings/proxy-limitsGet proxy timeout + body-size limits (admin).
POST/v1/settings/proxy-limitsUpdate proxy limits (admin). Body: {max_timeout_ms, max_body_bytes}. Range: 1 second to 30 minutes; 1 KiB to 100 MiB.

MCP#

MethodPathDescription
POST/v1/mcpMCP Streamable HTTP endpoint.
GET/v1/mcp/sseMCP SSE endpoint.
POST/v1/mcp/messageMCP SSE message handler.
GET/v1/mcp/toolsList MCP tools.

MCP tools#

ToolDescriptionCapability
gatehouse_getRead a secret valueread on path
gatehouse_leaseCheckout with TTLlease on path
gatehouse_revokeRevoke an active leaseOwner or admin
gatehouse_listList secret pathsread or list on path
gatehouse_putStore or update a secretwrite on path
gatehouse_scrubRedact credentials from textAny authenticated
gatehouse_proxyForward HTTP request with injectionproxy on each path
gatehouse_patternsQuery learned API patterns by pathread on path
gatehouse_statusHealth and identity infoAny authenticated