App Environment Variables API

The App Environment Variables API allows you to manage environment variables for app environments in Quave Cloud.

Make sure to read the Get Started document to understand how the API works.

Note: All endpoints in this API accept both appEnvId and envName parameters for identifying the environment.

List Environment Variables

Retrieves the list of environment variables for an app environment.

Endpoint: GET /api/public/v1/app-env/variables

Query Parameters

Parameter	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).
showSecrets	Boolean	No	If true, show decrypted secret values. Requires admin permission and quave:read:secrets scope. Default: false.

Example: List Variables (secrets masked)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/variables?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example Response (secrets masked)

{
  "variables": [
    {
      "_id": "abc123",
      "name": "NODE_ENV",
      "value": "production",
      "type": "DEPLOY",
      "isSecret": false
    },
    {
      "_id": "def456",
      "name": "DATABASE_URL",
      "value": "***SECRET***",
      "type": "DEPLOY",
      "isSecret": true
    },
    {
      "_id": "ghi789",
      "name": "BUILD_VERSION",
      "value": "1.2.3",
      "type": "BUILD",
      "isSecret": false
    }
  ]
}

Example: List Variables (with secrets)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/variables?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&showSecrets=true'

Example Response (with secrets)

{
  "variables": [
    {
      "_id": "abc123",
      "name": "NODE_ENV",
      "value": "production",
      "type": "DEPLOY",
      "isSecret": false
    },
    {
      "_id": "def456",
      "name": "DATABASE_URL",
      "value": "mongodb://user:pass@host:27017/db",
      "type": "DEPLOY",
      "isSecret": true
    }
  ]
}

Response Fields

Field	Type	Description
_id	String	Unique identifier for the variable.
name	String	Environment variable name.
value	String	Environment variable value. Masked as ***SECRET*** if isSecret is true and showSecrets is false.
type	String	When the variable is available: DEPLOY, BUILD, or BOTH.
isSecret	Boolean	Whether the variable is encrypted at rest.

---

Update Environment Variables

Adds, updates, or removes environment variables for an app environment. This is a partial update - only the variables you specify are modified; existing variables not in the request are left untouched.

Endpoint: PUT /api/public/v1/app-env/variables

Request Body

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).
variables	Array	No	Array of variables to add or update (see Variable Object).
variablesToRemove	Array	No	Array of variable names to remove.
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false.

Variable Object

Field	Type	Required	Description
name	String	Yes	Environment variable name.
value	String	Yes	Environment variable value.
isSecret	Boolean	No	Whether to encrypt the value. Default: false.
sendToBuild	Boolean	No	Whether to include during build phase. Default: false.
sendToDeploy	Boolean	No	Whether to include during deployment (runtime). Default: true.

Example: Add/Update Variables

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "variables": [
            {
                "name": "NEW_API_KEY",
                "value": "sk-abc123",
                "isSecret": true,
                "sendToDeploy": true
            },
            {
                "name": "DEBUG",
                "value": "true",
                "isSecret": false,
                "sendToBuild": true,
                "sendToDeploy": true
            }
        ],
        "applyImmediately": false
    }' \
    https://api.quave.cloud/api/public/v1/app-env/variables

Example: Remove Variables

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "variablesToRemove": ["OLD_VAR", "DEPRECATED_KEY"]
    }' \
    https://api.quave.cloud/api/public/v1/app-env/variables

Example: Add and Remove in One Request

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "variables": [
            {
                "name": "API_KEY",
                "value": "new-value",
                "isSecret": true
            }
        ],
        "variablesToRemove": ["OLD_API_KEY"],
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/variables

Example Response

{
  "success": true,
  "message": "Environment variables updated. Use apply-app-env-changes to deploy.",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production"
  },
  "appliedImmediately": false
}

Notes

• Partial Update: Only variables specified in variables are modified. Existing variables not in the request are unchanged.
• Order of Operations: Removals happen first, then adds/updates. This allows you to remove and re-add a variable with new settings in one request.
• Variable Types: Use sendToBuild and sendToDeploy to control when variables are available:
  • sendToDeploy: true only → DEPLOY type (runtime only)
  • sendToBuild: true only → BUILD type (build time only)
  • Both true → BOTH type (available at build and runtime)
• Secrets: Variables marked as isSecret: true are encrypted at rest and masked in the UI.
• Admin Required: Modifying environment variables requires admin permission on the account.

---

Error Responses

All endpoints may return the following error responses:

Status	Description
400	Invalid request (missing required fields, invalid values).
401	User not authenticated.
403	User doesn't have permission (admin required for modifications).
404	App environment not found for the given appEnvId or envName.