Secrets

Secrets API

Manage project secrets — API keys, tokens, and other credentials that your deployed project reads from process.env at runtime. Values are write-only: they go in through these endpoints and out through the deployed project's runtime, and are never returned in any API response.

For background on how secrets work and how they are stored, see the Secrets & Environment Variables guide.

List Secrets

GET /api/v1/projects/{projectId}/secrets

Returns the set of secrets defined on a project. Only the key name, the last four characters of the value, and timestamps are returned.

Response:

{
  "data": {
    "secrets": [
      {
        "key": "STRIPE_SECRET_KEY",
        "lastFour": "aB3x",
        "createdAt": "2026-04-18T09:12:44.000Z",
        "updatedAt": "2026-04-21T15:03:10.000Z"
      }
    ]
  }
}

Create or Update a Secret

POST /api/v1/projects/{projectId}/secrets

{ "key": "STRIPE_SECRET_KEY", "value": "sk_live_..." }

Idempotent by (projectId, key) — re-posting the same key overwrites the stored value. Updates never count against the per-project cap; only adding a new key does.

Key format: UPPER_SNAKE_CASE, 1–64 characters, must start with a letter. Value length: 1–4096 characters.

Response:

{
  "data": {
    "secret": {
      "key": "STRIPE_SECRET_KEY",
      "lastFour": "aB3x",
      "createdAt": "2026-04-18T09:12:44.000Z",
      "updatedAt": "2026-04-21T15:03:10.000Z"
    }
  }
}

Delete a Secret

DELETE /api/v1/projects/{projectId}/secrets/{key}

Removes a secret. Idempotent — deleting a key that does not exist still returns success: true, with existedindicating whether a row was actually removed.

Response:

{ "data": { "success": true, "existed": true } }

Errors

• 400 VALIDATION_ERROR — Body shape is wrong, the key fails the format check, or the value is empty or longer than 4096 characters.
• 404 NOT_FOUND— The project does not exist or the caller's API key is not scoped to it. For writes/deletes, the caller must also have admin role on the owning team.
• 409 SECRET_LIMIT_EXCEEDED — The project already has 25 secrets. Delete one or update an existing key instead of adding a new one.
• 429 RATE_LIMITED — API rate limit exceeded. See Error Handling for details.