App Environment Variables API

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

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 Secrets Access permission and quave:read:secrets scope. Default: false.
envVarNames	String	No*	Comma-separated names of the secrets to decrypt with showSecrets=true. Only these are decrypted; every other secret stays ***SECRET***. Unknown names return 404. *Required for MCP requests. Without it, a direct API call decrypts every secret in the environment.

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&envVarNames=DATABASE_URL'

Only DATABASE_URL is decrypted; any other secret in the environment stays ***SECRET***. Prefer naming the secrets you need over revealing the whole environment: each decrypted secret is recorded in the account audit log.

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.
valueHidden	Boolean	Only on a MySQL read replica's database credential variables (see below).
note	String	Only with valueHidden: why the value is hidden and where to manage users.

MySQL read replicas

A MySQL read replica uses the database users of its source database. On a replica, DB_USER_ADMIN, DB_PASS_ADMIN and DB_PASS_QC_ADMIN are still listed, but their value is null (with or without showSecrets), with valueHidden: true and a note that names the source. Create users, including read-only users (for example SELECT per schema), on the source environment; they reach the replica through replication. The same applies to the envVars returned by the get app env endpoint.

---

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: true.
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.

Secret revelation requires the account-level Secrets Access role; Admin alone does not grant it. Existing authentication, resource-access, MFA and API/MCP scope requirements still apply. See User Roles.