API Reference

API Reference

Complete REST API reference for secr. All endpoints accept and return JSON. An OpenAPI 3.1 spec is also available.

Overview

Base URL: https://api.secr.dev

All API routes are prefixed with /v1. For example, /v1/auth/me.

Authentication

Two methods are supported:

  • Session cookie — __secr_session (used by the dashboard)
  • Bearer token — Authorization: Bearer secr_tok_... (used by the CLI and SDKs)

CSRF Protection

Cookie-authenticated mutations require the X-Requested-With: secr header. Token-authenticated requests do not need this header.

Example request
curl -X GET https://api.secr.dev/v1/auth/me \
  -H "Authorization: Bearer secr_tok_abc123"

Auth

MethodRouteDescription
POST/auth/registerCreate account + personal org
POST/auth/loginLogin, returns session cookie
POST/auth/logoutClear session
GET/auth/meCurrent user + orgs
POST/auth/tokenCreate a scoped CLI token
POST/auth/cli-authDashboard-to-CLI token handoff
GET/auth/tokensList active CLI tokens
DELETE/auth/tokens/:tokenIdRevoke a CLI token
POST/auth/change-passwordChange password (requires auth)
POST/auth/send-verificationSend email verification link
POST/auth/verify-emailVerify email with token
POST/auth/forgot-passwordRequest password reset (rate-limited)
POST/auth/reset-passwordReset password with token

Projects

MethodRouteDescription
GET/projects/:orgIdList projects in org
POST/projects/:orgIdCreate project (owner/admin)
GET/projects/:orgId/:slugGet project details
DELETE/projects/:orgId/:slugDelete project (owner only)
POST/projects/:orgId/:slug/environmentsCreate custom environment
POST/projects/:orgId/:slug/rotate-keyRotate encryption key (owner/admin)

Secrets

Secret routes use org slugs, not IDs.

MethodRouteDescription
GET/secrets/:orgSlug/:project/:envPull all secrets (decrypted)
GET/secrets/:orgSlug/:project/:env/keysList keys only (no values)
PUT/secrets/:orgSlug/:project/:envSet a secret
POST/secrets/:orgSlug/:project/:env/bulkBulk import secrets
GET/secrets/:orgSlug/:project/:env/versions/:keySecret version history
POST/secrets/:orgSlug/:project/promotePromote secrets between envs
POST/secrets/:orgSlug/:project/:env/bulk-deleteBulk delete secrets (owner/admin)
DELETE/secrets/:orgSlug/:project/:env/:keySoft-delete a secret

Pagination & Search

The GET secrets and GET keys endpoints support optional pagination and key prefix search:

OptionTypeRequiredDescription
limitintomit = allMax results per page (1-500)
offsetint0Number of results to skip
searchstringNoFilter keys by prefix (case-sensitive)

When limit is provided, the response includes a pagination object with { limit, offset, total }. When omitted, all results are returned.

Pagination example
GET /v1/secrets/my-org/my-proj/development?limit=10&offset=0
GET /v1/secrets/my-org/my-proj/development/keys?search=DB_&limit=20

// Response:
{
  "secrets": [...],
  "pagination": { "limit": 10, "offset": 0, "total": 42 }
}

Organizations

MethodRouteDescription
POST/orgsCreate organization
DELETE/orgs/:orgIdDelete organization (owner only, cascades all data)

Templates

Templates define required secret keys for a project. Validate an environment against the template to catch missing configuration.

MethodRouteDescription
GET/templates/:orgSlug/:projectList template keys
POST/templates/:orgSlug/:projectAdd a template key (admin/owner)
DELETE/templates/:orgSlug/:project/:keyRemove a template key (admin/owner)
GET/templates/:orgSlug/:project/validate/:envValidate env against template

Webhooks

Webhooks fire on secret events: secret.created, secret.updated, secret.deleted, secret.bulk_set, secret.promoted, secret.bulk_delete.

MethodRouteDescription
GET/webhooks/:orgIdList webhooks
POST/webhooks/:orgIdCreate webhook (admin/owner)
GET/webhooks/:orgId/:idGet webhook + delivery log
PATCH/webhooks/:orgId/:idUpdate webhook
DELETE/webhooks/:orgId/:idDelete webhook
POST/webhooks/:orgId/:id/testSend test delivery

Members

MethodRouteDescription
GET/members/:orgIdList members + pending invites
POST/members/:orgId/inviteInvite a member
POST/members/invite/:token/acceptAccept invitation
PATCH/members/:orgId/:idChange member role (owner only)
DELETE/members/:orgId/:idRemove member (owner/admin)

Audit

MethodRouteDescription
GET/audit/:orgIdQuery audit log

Supports query parameters: ?limit=&offset=&action=

Billing

Stripe-powered billing with hosted Checkout and Customer Portal.

MethodRouteDescription
GET/billing/:orgIdBilling status + usage counts
POST/billing/:orgId/checkoutCreate Stripe Checkout session
POST/billing/:orgId/portalCreate Stripe Customer Portal session
POST/billing/webhookStripe webhook (no auth, signature verified)

Admin

All admin routes require isAdmin = true on the authenticated user. Returns 403 for non-admin users.

MethodRouteDescription
GET/admin/statsPlatform stats (users, orgs, projects)
GET/admin/orgsList all orgs with usage counts
GET/admin/orgs/:orgIdOrg detail + effective plan limits
PATCH/admin/orgs/:orgIdUpdate org plan and/or limit overrides
GET/admin/plansList all plan configs
PUT/admin/plans/:planNameUpdate a plan's default limits
GET/admin/metrics/summaryRequest metrics (?hours=N, default 24, max 168)

Plan limit resolution

Effective limits are resolved in priority order:

  1. Per-org overrides — limitOverrides on the org (highest priority)
  2. DB plan config — plan_configs table (runtime-editable defaults)
  3. Hardcoded constants — PLAN_LIMITS in @secr/shared (fallback)

Use -1 in the DB/API to represent unlimited (translates to Infinity internally).

Roles and Permissions

Access control is role-based. Each member has one of four roles:

PermissionOwnerAdminDeveloperViewer
Read secretsAll envsAll envsdev + stagingdev only
Write secretsYesYesYesNo
Promote secretsYesYesYesNo
Manage templatesYesYesNoNo
Manage membersYesYesNoNo
Delete projectsYesNoNoNo
View audit logYesYesNoNo

Start building with the API

curl https://api.secr.dev/v1/auth/me \

-H "Authorization: Bearer secr_tok_..."

Create Free AccountBack to Docs