API reference

The Secronna REST API. Resources nest: projects own environments, environments own secrets.

Base URL

https://secronna.com/api/v1

Authentication

Every request carries a Bearer token — a per-workspace API key (sk_live_xxx) from Settings → API keys, or a Huudis-minted access token:

Authorization: Bearer sk_live_xxx

Requests without a valid token fail with AUTH_REQUIRED. Secronna is in private beta, so the token's workspace must be on the allowlist.

Response envelope

Every response uses the family-standard envelope:

{
  "data": { },
  "error": null,
  "meta": { "requestId": "req_...", "timestamp": "2026-01-01T00:00:00Z" }
}

List endpoints put an array in data and page info in meta. On error, data is null and error carries an UPPER_SNAKE_CASE code plus a human-readable message:

{
  "data": null,
  "error": { "code": "NOT_FOUND", "message": "secret not found" },
  "meta": { "requestId": "req_...", "timestamp": "2026-01-01T00:00:00Z" }
}

Common codes: AUTH_REQUIRED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, INTERNAL_ERROR.

Projects

Create a project

POST /projects

Request:

{ "name": "Web" }

Response data:

{
  "id": "proj_...",
  "name": "Web",
  "slug": "web",
  "createdAt": "2026-01-01T00:00:00Z",
  "createdBy": "usr_..."
}

List projects

GET /projects

data is an array of the project objects above.

Environments

Create an environment

POST /projects/:projectId/environments

Request:

{ "name": "production" }

Response data:

{
  "id": "env_...",
  "name": "production",
  "slug": "production",
  "createdAt": "2026-01-01T00:00:00Z"
}

List environments

GET /projects/:projectId/environments

data is an array of the environment objects above.

Secrets

Secrets are immutable and versioned. Writing a key mints a new version; listing returns keys only; reading a value is an explicit, audited reveal.

Write a secret

PUT /environments/:envId/secrets

Creates the key if it doesn't exist, otherwise mints the next version.

Request:

{ "key": "DATABASE_URL", "value": "postgres://user:pass@host/db" }

Response data:

{ "id": "sec_...", "key": "DATABASE_URL", "version": 1 }

List secrets (keys only)

GET /environments/:envId/secrets

data is an array — values are never included here:

[
  {
    "id": "sec_...",
    "key": "DATABASE_URL",
    "currentVersion": 3,
    "createdAt": "2026-01-01T00:00:00Z"
  }
]

Reveal a secret

POST /secrets/:secretId/reveal

Returns the plaintext of a single version. Every reveal is written to the audit log. Pass ?version=<n> to read a historical version; omit it for the current version.

Response data:

{ "key": "DATABASE_URL", "version": 3, "value": "postgres://user:pass@host/db" }

Delete a secret

DELETE /secrets/:secretId

Deletes the secret and all its versions.

Response data:

{ "id": "sec_...", "deleted": true }

Audit

List audit entries

GET /audit?limit=<n>

Recent audit-log entries — reveals, writes, deletes, project/environment creation. limit caps how many are returned.

data is an array:

[
  {
    "id": "aud_...",
    "action": "secret.reveal",
    "actorSub": "usr_...",
    "target": "sec_...",
    "metadata": { "key": "DATABASE_URL", "version": 3 },
    "createdAt": "2026-01-01T00:00:00Z"
  }
]