Environment Variables API

Manage environment variables and secrets for your projects.

Where the values live

For an app, these endpoints read and write the variables at its provider (Vercel or Google Cloud Run). On Vercel a change rebuilds the live deployment. Values are masked in list responses unless ?show=true is passed, which needs the env.values.read permission. 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
  }
}