Environment Variables API

Manage environment variables and secrets for your projects.

Encryption

Values are encrypted at rest (AES-256-GCM). Secret values are masked in list responses unless ?show=true is passed. All endpoints require a Bearer token — see Authentication.

Set Variables

POST /projects/:id/env

Bulk upsert environment variables. Creates new variables and updates existing ones in a single call (1–100 variables per request).

Permission: env.write

Request Body

Parameter	Type	Required	Description
`vars`	array	Yes	Array of variable objects (1–100 items)
`vars[].key`	string	Yes	Variable name (1–255 chars)
`vars[].value`	string	Yes	Variable value
`vars[].isSecret`	boolean	No	Mark as secret (masked in UI and list responses)
`serviceId`	string	No	Scope to a specific service UUID

Request

{
  "vars": [
    { "key": "DATABASE_URL", "value": "postgresql://...", "isSecret": true },
    { "key": "NEXT_PUBLIC_API_URL", "value": "https://api.acme.com" },
    { "key": "JWT_SECRET", "value": "super-secret-key", "isSecret": true }
  ]
}

Response (200)

{
  "success": true,
  "data": {
    "created": ["DATABASE_URL", "JWT_SECRET"],
    "updated": ["NEXT_PUBLIC_API_URL"],
    "unchanged": [],
    "message": "3 variables synced"
  }
}

List Variables

GET /projects/:id/env

List all environment variables for a project. Secret values are masked unless ?show=true is passed.

Permission: env.list (values require env.values.read)

Query Parameters

Parameter	Type	Default	Description
`show`	string	—	Set to `true` to reveal secret values
`serviceId`	string	—	Filter by service UUID

Response (200)

{
  "success": true,
  "data": {
    "vars": [
      { "key": "DATABASE_URL", "value": "********", "isSecret": true },
      { "key": "NEXT_PUBLIC_API_URL", "value": "https://api.acme.com", "isSecret": false },
      { "key": "JWT_SECRET", "value": "********", "isSecret": true }
    ],
    "count": 3
  }
}

Get Variable

GET /projects/:id/env/:key

Get a single environment variable by key, including its value.

Permission: env.values.read

Response (200)

{
  "success": true,
  "data": {
    "key": "DATABASE_URL",
    "value": "postgresql://user:pass@host:5432/db"
  }
}

Delete Variable

DELETE /projects/:id/env/:key

Delete a single environment variable by key.

Permission: env.write

Query Parameters

Parameter	Type	Default	Description
`serviceId`	string	—	Scope to a specific service UUID

Response (200)

{
  "success": true,
  "data": {
    "message": "Variable 'DATABASE_URL' deleted"
  }
}

Generate Secrets

POST /projects/:id/env/generate

Auto-generate cryptographically secure values for common secret keys (e.g. JWT_SECRET, SESSION_SECRET, NEXTAUTH_SECRET).

Permission: env.write

Response (200)

{
  "success": true,
  "data": {
    "generated": ["JWT_SECRET", "SESSION_SECRET", "NEXTAUTH_SECRET"],
    "message": "3 secrets generated"
  }
}

Compare Variables

POST /projects/:id/env/diff

Compare local environment variables against the remote state. Useful for detecting drift between your .env.local file and the deployed configuration.

Permission: env.list

Request Body

Parameter	Type	Required	Description
`vars`	array	Yes	Array of local variables to compare
`vars[].key`	string	Yes	Variable name
`vars[].value`	string	Yes	Variable value
`serviceId`	string	No	Scope to a specific service UUID

Request

{
  "vars": [
    { "key": "DATABASE_URL", "value": "postgresql://localhost:5432/dev" },
    { "key": "API_KEY", "value": "old-key" }
  ]
}

Response (200)

{
  "success": true,
  "data": {
    "added": ["JWT_SECRET"],
    "removed": [],
    "changed": ["DATABASE_URL"],
    "unchanged": ["API_KEY"],
    "hasChanges": true
  }
}