Secrets API
Manage encrypted secrets with version history, rollback, and bulk import/export.
All secret values are encrypted at rest using AES-256-GCM with a master key (SECRETS_ENCRYPTION_KEY environment variable).
GET /api/projects/:projectId/secrets
Lists all active secrets for a project. Values are masked (***). Requires secrets.list permission.
Auth: Bearer token (secrets.list permission)
Response 200:
[
{
"id": "uuid",
"key": "DATABASE_URL",
"environmentId": "uuid-or-null",
"version": 3,
"maskedValue": "***",
"createdById": "uuid",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-07-01T12:00:00.000Z"
}
]
POST /api/projects/:projectId/secrets
Creates or updates a secret. If a secret with the same key and environmentId exists, the previous version is saved to history and the version is incremented. Requires secrets.create permission. Audit-logged.
Auth: Bearer token (secrets.create permission)
Request Body:
{
"key": "DATABASE_URL",
"value": "postgresql://user:pass@host:5432/db",
"environmentId": "uuid-or-null"
}
Response 201:
{
"id": "uuid",
"key": "DATABASE_URL",
"environmentId": "uuid",
"version": 3
}
POST /api/projects/:projectId/secrets/reveal
Reveals a secret's plaintext value. This action is audit-logged with the key and environment. Requires secrets.reveal permission.
Auth: Bearer token (secrets.reveal permission)
Request Body:
{
"environmentId": "uuid",
"key": "DATABASE_URL"
}
Response 200:
{
"id": "uuid",
"key": "DATABASE_URL",
"value": "postgresql://user:pass@host:5432/db",
"environmentId": "uuid",
"version": 3
}
Error 500:
{ "error": "SECRETS_ENCRYPTION_KEY not configured" }
DELETE /api/projects/:projectId/secrets/:secretId
Soft-deletes a secret by setting isActive = false. Requires secrets.delete permission. Audit-logged.
Auth: Bearer token (secrets.delete permission)
Response 200:
{ "success": true }
GET /api/projects/:projectId/secrets/export/:environmentId
Exports all secrets for an environment as a .env-formatted string. Values are decrypted before export. Requires secrets.export permission. Audit-logged.
Auth: Bearer token (secrets.export permission)
Response 200:
{
"environmentId": "uuid",
"secrets": "DATABASE_URL=postgresql://user:pass@host:5432/db\nAPI_KEY=sk-abc123\n"
}
POST /api/projects/:projectId/secrets/bulk
Bulk imports secrets as an array of {key, value} objects. Existing keys are updated with incremented versions; new keys are created. Requires secrets.import permission. Audit-logged.
Auth: Bearer token (secrets.import permission)
Request Body:
{
"environmentId": "uuid",
"secrets": [
{ "key": "DATABASE_URL", "value": "postgresql://..." },
{ "key": "API_KEY", "value": "sk-abc123" }
]
}
Response 201:
{
"imported": 2,
"results": [
{ "key": "DATABASE_URL", "status": "updated", "version": 4 },
{ "key": "API_KEY", "status": "created", "version": 1 }
]
}
Version History
GET /api/projects/:projectId/secrets/:secretId/versions
Returns the version history for a secret. Requires secrets.list permission.
Response 200:
{
"key": "DATABASE_URL",
"currentVersion": 4,
"history": [
{ "version": 3, "changedById": "uuid", "changedAt": "2026-06-01T00:00:00.000Z" },
{ "version": 2, "changedById": "uuid", "changedAt": "2026-05-01T00:00:00.000Z" },
{ "version": 1, "changedById": "uuid", "changedAt": "2026-04-01T00:00:00.000Z" }
]
}
Rollback
POST /api/projects/:projectId/secrets/:secretId/rollback/:version
Rolls back a secret to a previous version. The current version is saved to history first, then the target version's encrypted value is restored. The version counter is incremented. Requires secrets.rollback permission. Audit-logged.
Auth: Bearer token (secrets.rollback permission)
Response 200:
{
"success": true,
"key": "DATABASE_URL",
"version": 5,
"rolledBackTo": 2
}
Error 400:
{ "error": "Version 5 is not a previous version (current: 6)" }
Error Codes
| Status | Error | Description |
|---|---|---|
| 400 | key and value are required |
Missing fields on create |
| 400 | Invalid version number |
Rollback version is not a number |
| 400 | secrets must be a non-empty array... |
Invalid bulk import payload |
| 404 | Secret not found |
Secret does not exist |
| 404 | Version X not found in history |
Target version does not exist |
| 500 | SECRETS_ENCRYPTION_KEY not configured |
Missing encryption key environment variable |
| 500 | Failed to decrypt secret |
Encryption/decryption error |