REST API reference
All endpoints are namespaced under /v1 (except the runtime API and
health check). Authentication is per-route — most use a session cookie
(better-auth), the runtime API uses an Authorization: Bearer shush_… API
key. Each section links to the source file in the repo for body/response
shapes.
Health
| Method | Path | Notes |
|---|---|---|
| GET | /health | Postgres + Redis liveness probe. |
Source: apps/api/src/routes/health.ts.
Me
The current user’s profile.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/me | Return current user. |
| PATCH | /v1/me | Update current user (name, avatar). |
Source: me.ts.
Organizations
| Method | Path | Notes |
|---|---|---|
| GET | /v1/orgs/me | List orgs the current user belongs to. |
| POST | /v1/orgs | Create a new org. |
| GET | /v1/orgs/current | Get the active org. |
| POST | /v1/orgs/current | Switch active org. |
| PATCH | /v1/orgs/current | Update active org metadata. |
| DELETE | /v1/orgs/current | Delete the active org. |
| POST | /v1/orgs/current/2fa/setup | Begin TOTP enrollment for the org. |
| GET | /v1/orgs/current/encryption | Get the org’s encryption state. |
| POST | /v1/orgs/current/rotate-kek | Rotate the org’s DEK wrapping. |
Source: orgs.ts.
Projects
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects | List projects. |
| GET | /v1/projects/:projectId | Fetch a project. |
| POST | /v1/projects | Create a project. |
| DELETE | /v1/projects/:projectId | Delete a project. |
Source: projects.ts.
Environments
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/environments | List a project’s envs. |
| PATCH | /v1/projects/:projectId/environments | Update env config (parents). |
Source: environments.ts.
Folders
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/folders | List folders. |
| POST | /v1/projects/:projectId/folders | Create a folder. |
| PATCH | /v1/projects/:projectId/folders/:id | Rename / move. |
| DELETE | /v1/projects/:projectId/folders/:id | Delete a folder. |
Source: folders.ts.
Secrets
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/secrets | List secrets in a project. |
| GET | /v1/projects/:projectId/secrets/:id | Fetch one secret (all envs). |
| POST | /v1/projects/:projectId/secrets | Create a secret. |
| PATCH | /v1/projects/:projectId/secrets/:id | Update a secret value / metadata. |
| DELETE | /v1/projects/:projectId/secrets/:id | Delete a secret. |
| POST | /v1/projects/:projectId/secrets/:id/rotate | Mark a secret as rotated. |
| GET | /v1/projects/:projectId/secrets/:id/versions | List a secret’s version history. |
| GET | /v1/projects/:projectId/secrets/export | Export an env to dotenv / shell / JSON. |
| POST | /v1/projects/:projectId/secrets/import | Import a dotenv file. |
| GET | /v1/projects/:projectId/secrets/:id/rotation-policy | Read rotation policy. |
| POST | /v1/projects/:projectId/secrets/:id/rotation-policy | Set rotation policy. |
| DELETE | /v1/projects/:projectId/secrets/:id/rotation-policy | Clear rotation policy. |
Source: secrets.ts.
Shared secrets
Org-wide secret store, mounted under /v1/orgs/current.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/orgs/current/shared-folders | List org-wide folders. |
| GET | /v1/orgs/current/shared-secrets | List org-wide secrets. |
| GET | /v1/orgs/current/shared-secrets/:id | Fetch one shared secret. |
| POST | /v1/orgs/current/shared-secrets | Create a shared secret. |
| GET | /v1/orgs/current/shared-secrets/:id/versions | Shared secret version history. |
Source: shared.ts.
API keys
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/api-keys | List API keys. |
| POST | /v1/projects/:projectId/api-keys | Create a key (plaintext shown once). |
| POST | /v1/projects/:projectId/api-keys/:id/rotate | Rotate a key. |
| POST | /v1/projects/:projectId/api-keys/:id/revoke | Revoke a key. |
| DELETE | /v1/projects/:projectId/api-keys/:id | Hard-delete a key. |
Source: api-keys.ts.
Webhooks
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/webhooks | List webhooks. |
| POST | /v1/projects/:projectId/webhooks | Create a webhook. |
| PATCH | /v1/projects/:projectId/webhooks/:id | Update a webhook. |
| DELETE | /v1/projects/:projectId/webhooks/:id | Delete a webhook. |
| POST | /v1/projects/:projectId/webhooks/:id/test | Fire a test delivery. |
| GET | /v1/projects/:projectId/webhooks/:id/deliveries | List recent deliveries. |
Source: webhooks.ts.
Integrations
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/integrations | List integrations. |
| POST | /v1/projects/:projectId/integrations | Create an integration. |
| GET | /v1/projects/:projectId/integrations/sync-status | Per-integration sync status. |
| DELETE | /v1/projects/:projectId/integrations/:id | Delete an integration. |
Source: integrations.ts.
Audit
| Method | Path | Notes |
|---|---|---|
| GET | /v1/audit | Page through the audit log. |
| GET | /v1/audit/export | Export the audit log as CSV / JSON. |
Source: audit.ts.
Access (members + invitations)
| Method | Path | Notes |
|---|---|---|
| GET | /v1/access/members | List org members. |
| PATCH | /v1/access/members/:memberId | Update a member’s role. |
| DELETE | /v1/access/members/:memberId | Remove a member. |
| GET | /v1/access/invitations | List pending invitations. |
| POST | /v1/access/invitations | Send an invitation. |
| POST | /v1/access/invitations/:id/cancel | Cancel an invitation. |
| GET | /v1/access/permissions | Static permission catalog. |
| GET | /v1/access/members/me/permissions | The caller’s effective permissions. |
Source: access.ts.
Counts
| Method | Path | Notes |
|---|---|---|
| GET | /v1/projects/:projectId/counts | Counts per resource type. |
| GET | /v1/projects/:projectId/env-counts | Counts per environment. |
Source: counts.ts.
CLI auth (device-code flow)
Used by shush login.
| Method | Path | Notes |
|---|---|---|
| POST | /v1/auth/cli/start | Begin a device-code flow. |
| POST | /v1/auth/cli/approve | Approve a pending device code (dashboard). |
| POST | /v1/auth/cli/enable | Mint the API key once approved. |
Source: auth/cli.ts.
Runtime
Bearer-token API used by @shushsecrets/inject. Lives under /runtime/v1.
| Method | Path | Notes |
|---|---|---|
| GET | /runtime/v1/ | Token introspection. |
| GET | /runtime/v1/secrets | Fetch all secrets for the token’s env. |
| GET | /runtime/v1/secrets/:key | Fetch a single secret. |
Source: runtime.ts.
Billing
Stripe-backed subscription management. Session-authenticated unless noted.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/billing/current | Current plan, status, period end, seat usage, seat limit. |
| POST | /v1/billing/checkout | Owner only. Creates a Stripe Checkout session for a plan. |
| POST | /v1/billing/portal | Owner only. Creates a Stripe billing-portal session. |
| POST | /v1/billing/webhook | Unauthenticated. Stripe webhook receiver (HMAC verified). |
Required env: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_TEAM, STRIPE_PRICE_ENTERPRISE.
Source: billing.ts.
BYOK (KMS)
Bring-your-own KEK via AWS KMS. Owner only.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/orgs/current/kms | Current BYOK config (no secrets). |
| POST | /v1/orgs/current/kms/test | Validate IAM creds + key existence via DescribeKey. |
| POST | /v1/orgs/current/kms/enable | Atomically re-wraps the org DEK with KMS and flips the provider. |
| DELETE | /v1/orgs/current/kms | Re-wraps with MASTER_KEK_B64 and disables BYOK. |
Provider selection is per-org: any org without an enabled kms_key row continues to use the server-wide MASTER_KEK_B64.
Source: kms.ts.
SSO (SAML)
SAML 2.0 via @boxyhq/saml-jackson. Per-org.
| Method | Path | Notes |
|---|---|---|
| GET | /v1/sso/by-domain?domain=… | Public. Resolve an email domain to an SSO-enabled orgId. |
| GET | /v1/sso/saml/metadata?orgId=… | Public. Service-provider metadata XML. |
| GET | /v1/sso/saml/connections | Read the org’s SAML connection (mirror). |
| POST | /v1/sso/saml/connections | Owner only. Wraps Jackson createSAMLConnection. |
| DELETE | /v1/sso/saml/connections/:clientID | Owner only. Disables the org’s SSO. |
| GET | /v1/sso/saml/authorize | Initiate SAML login. Redirects to the IdP. |
| POST | /v1/sso/saml/acs | Public. SAML assertion consumer service. |
| GET | /v1/sso/saml/oauth-callback | Internal: exchanges Jackson’s OAuth code for a shush session. |
| GET | /v1/sso/scim/tokens | Admin. List SCIM bearer tokens. |
| POST | /v1/sso/scim/tokens | Admin. Mint a SCIM token (plaintext returned once). |
| DELETE | /v1/sso/scim/tokens/:id | Admin. Revoke a SCIM token. |
Required env: JACKSON_SAML_AUDIENCE, JACKSON_EXTERNAL_URL (falls back to BETTER_AUTH_URL).
Source: sso.ts.
SCIM v2
User and group provisioning for IdPs (Okta, Azure AD, etc.) at /scim/v2. Bearer-token auth; tokens are minted from the SSO panel above.
| Method | Path | Notes |
|---|---|---|
| GET | /scim/v2/ServiceProviderConfig | RFC 7644 SP config document. |
| GET | /scim/v2/Users | List members. Supports filter=userName eq "...", startIndex, count. |
| POST | /scim/v2/Users | Provision a user into the org (role defaults to engineer). |
| GET | /scim/v2/Users/:id | Single member. |
| PATCH | /scim/v2/Users/:id | Soft-delete via active=false (sets member.removedAt). |
| DELETE | /scim/v2/Users/:id | Same effect as PATCH active=false. |
| GET | /scim/v2/Groups | One group per role (owner / admin / engineer / viewer). |
| GET | /scim/v2/Groups/:id | Members of that role group. |
Source: scim.ts.
Last updated on