Secrets
API reference for managing project secrets.
List Secrets
Returns metadata for all secrets in the project. Plaintext values are never included.
GET /v1/projects/:projectId/secretsQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
environment | string | No | Only return secrets scoped to this environment. One of default, development, staging, production. |
Response
{
"success": true,
"data": [
{
"id": "clx...",
"name": "DB_PASSWORD",
"description": "Production database password",
"environment": "default",
"version": 2,
"createdBy": "user_...",
"updatedBy": "user_...",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-16T08:00:00.000Z",
"createdByUser": { "id": "user_...", "name": "Jane", "email": "[email protected]" },
"updatedByUser": { "id": "user_...", "name": "Jane", "email": "[email protected]" }
}
]
}Get Secret
GET /v1/projects/:projectId/secrets/:secretIdReturns metadata for a single secret.
Get Usage
GET /v1/projects/:projectId/secrets/usageResponse
{
"success": true,
"data": {
"used": 3,
"limit": 5,
"freeLimit": 5,
"packSize": 5,
"paidPacks": 0,
"packPrice": { "monthly": 200, "currency": "USD" }
}
}packPrice is the monthly price of one secrets pack (monthly in cents, currency as an ISO 4217 code), or null if no active price is configured. It is resolved from the Stripe price catalogue and does not depend on whether the project has purchased a pack yet.
Create Secret
Requires secrets:write scope and owner/admin role.
POST /v1/projects/:projectId/secretsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Uppercase letters, numbers, underscores. Must start with a letter. |
value | string | Yes | The secret value (1–10,000 characters). |
description | string | No | Optional description (max 500 characters). |
environment | string | No | Environment to scope the secret to: default, development, staging, or production. Defaults to default, which applies everywhere. |
Response 201
{
"success": true,
"data": {
"id": "clx...",
"name": "DB_PASSWORD",
"description": "Production database password",
"environment": "default",
"version": 1,
"value": "my-super-secret-value",
"maskedValue": "my••••ue",
"createdAt": "2025-01-15T10:30:00.000Z"
}
}The value field is only returned in this response. It cannot be retrieved again.
Error 402
Returned when the project has reached its secret limit. Add a secrets pack via the upgrade endpoint.
Error 409
Returned when a secret with the same name already exists in the same environment. The same name can be reused across different environments.
Update Secret
Requires secrets:write scope and owner/admin role.
PATCH /v1/projects/:projectId/secrets/:secretIdRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
value | string | Yes | The new secret value. |
description | string | No | Updated description. |
Response
Returns the updated secret with the new plaintext value (shown once).
Delete Secret
Requires secrets:write scope and owner/admin role.
DELETE /v1/projects/:projectId/secrets/:secretIdReturns 204 No Content on success.
Upgrade (Add Secrets Packs)
Adds one or more packs of 5 additional secrets to the project limit. Billed as a subscription item on the project's Stripe subscription, with proration.
POST /v1/projects/:projectId/secrets/upgradeRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
packs | number | No | Number of packs to add, between 1 and 20. Defaults to 1. |
Response
Returns the updated usage data (same shape as the usage endpoint).
Error 402
Returned when the project has no active Stripe subscription yet. Add a paid resource to the project first so a subscription exists, then retry the upgrade.
Audit Trail
Returns the audit log for a specific secret. Requires owner/admin role.
GET /v1/projects/:projectId/secrets/:secretId/auditResponse
{
"success": true,
"data": [
{
"id": "clx...",
"secretId": "clx...",
"action": "CREATED",
"actor": { "id": "user_...", "name": "Jane", "email": "[email protected]" },
"createdAt": "2025-01-15T10:30:00.000Z"
}
]
}Actions: CREATED, UPDATED, DELETED.