Set environment variables

Create or update environment variables for an environment in a single atomic request.

By default this is an upsert: each variable in the payload is created if new or fully overwritten if the key already exists, and any variable not in the payload is left untouched. This lets you change one variable without re-sending the others, which matters for write-only secrets you can no longer read back.

Set prune: true to make it a full replace instead: after upserting, every variable not in the payload is deleted. Sending prune: true with an empty variables list resets the environment by deleting every variable.

Each variable is written exactly as sent, never merged, so omitted optional fields fall back to their defaults rather than the previous value. Values are always encrypted at rest. Set kind: recoverable to allow a value to be read back; it defaults to writeonly, which can never be read back through the API.

Required Permissions

Your root key must have one of the following permissions:

environment.*.set_environment_variables (for any environment)
environment.<environment_id>.set_environment_variables (for a specific environment)

POST

environments.setEnvironmentVariables

Python (SDK)

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.environments.set_environment_variables(project="payments", app="payments-api", environment="production", variables=[
        {
            "key": "DATABASE_URL",
            "value": "postgresql://user:pass@host:5432/db",
        },
        {
            "key": "LOG_LEVEL",
            "value": "debug",
            "kind": models.Kind.RECOVERABLE,
            "description": "Application log verbosity",
        },
    ], prune=True)

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.environments.setEnvironmentVariables({
    project: "payments",
    app: "payments-api",
    environment: "production",
    variables: [
      {
        key: "DATABASE_URL",
        value: "postgresql://user:pass@host:5432/db",
      },
      {
        key: "LOG_LEVEL",
        value: "debug",
        kind: "recoverable",
        description: "Application log verbosity",
      },
    ],
    prune: true,
  });

  console.log(result);
}

run();

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Environments.SetEnvironmentVariables(ctx, components.V2EnvironmentsSetEnvironmentVariablesRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
        Variables: []components.EnvironmentVariableInput{
            components.EnvironmentVariableInput{
                Key: "DATABASE_URL",
                Value: "postgresql://user:pass@host:5432/db",
            },
            components.EnvironmentVariableInput{
                Key: "LOG_LEVEL",
                Value: "debug",
                Kind: components.KindRecoverable.ToPointer(),
                Description: unkey.Pointer("Application log verbosity"),
            },
        },
        Prune: unkey.Pointer(true),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2EnvironmentsSetEnvironmentVariablesResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/environments.setEnvironmentVariables \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "environment": "production",
  "project": "payments",
  "prune": true,
  "variables": [
    {
      "key": "DATABASE_URL",
      "kind": "writeonly",
      "value": "postgresql://user:pass@host:5432/db"
    },
    {
      "description": "Application log verbosity",
      "key": "LOG_LEVEL",
      "kind": "recoverable",
      "value": "debug"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    environment: 'production',
    project: 'payments',
    prune: true,
    variables: [
      {
        key: 'DATABASE_URL',
        kind: 'writeonly',
        value: 'postgresql://user:pass@host:5432/db'
      },
      {
        description: 'Application log verbosity',
        key: 'LOG_LEVEL',
        kind: 'recoverable',
        value: 'debug'
      }
    ]
  })
};

fetch('https://api.unkey.com/v2/environments.setEnvironmentVariables', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/environments.setEnvironmentVariables",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'environment' => 'production',
    'project' => 'payments',
    'prune' => true,
    'variables' => [
        [
                'key' => 'DATABASE_URL',
                'kind' => 'writeonly',
                'value' => 'postgresql://user:pass@host:5432/db'
        ],
        [
                'description' => 'Application log verbosity',
                'key' => 'LOG_LEVEL',
                'kind' => 'recoverable',
                'value' => 'debug'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/environments.setEnvironmentVariables")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"prune\": true,\n  \"variables\": [\n    {\n      \"key\": \"DATABASE_URL\",\n      \"kind\": \"writeonly\",\n      \"value\": \"postgresql://user:pass@host:5432/db\"\n    },\n    {\n      \"description\": \"Application log verbosity\",\n      \"key\": \"LOG_LEVEL\",\n      \"kind\": \"recoverable\",\n      \"value\": \"debug\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/environments.setEnvironmentVariables")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"prune\": true,\n  \"variables\": [\n    {\n      \"key\": \"DATABASE_URL\",\n      \"kind\": \"writeonly\",\n      \"value\": \"postgresql://user:pass@host:5432/db\"\n    },\n    {\n      \"description\": \"Application log verbosity\",\n      \"key\": \"LOG_LEVEL\",\n      \"kind\": \"recoverable\",\n      \"value\": \"debug\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {}
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Authorizations

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

project

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

app

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

environment

string

required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

variables

object[]

required

The variables to upsert. Each entry is created if its key is new or fully overwritten if the key already exists. Existing variables whose keys are not in this list are left untouched, unless prune is true.

Each entry is written exactly as sent, never merged with the current state. Only value is required; omitted optional fields (kind, description) fall back to their defaults rather than any previous value, so overwriting a variable without a description clears it.

Each key may appear at most once; a duplicate key is rejected with a 400. The whole operation is atomic: if any part fails the environment is left unchanged. All values are encrypted at rest. Limited to 50 variables per request.

Maximum array length: 50

Show child attributes

prune

boolean

default:false

Optional. Defaults to false. When false, the variables above are upserted and any existing variable not in the list is kept. When true, this becomes a full replace: after upserting, every variable not in the list is deleted. Combined with an empty variables list, prune: true resets the entire environment by deleting every variable.

Response

Successfully set the environment variables.

meta

object

required

Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The requestId is particularly important when troubleshooting issues with the Unkey support team.

Show child attributes

data

object

required

Empty response object by design. A successful response indicates this operation was successfully executed.

Last modified on July 22, 2026

Update environment settingsUpdate the build, runtime, and regional settings for an environment. All settings fields are optional. Omit a field to leave it unchanged. For nullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null to clear the value. When `regions` is present it replaces the full set of regions for the environment. **Required Permissions** Your root key must have one of the following permissions: - `environment.*.update_environment` (to update any environment) - `environment.<environment_id>.update_environment` (to update a specific environment)

⌘I

Python (SDK)

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.environments.set_environment_variables(project="payments", app="payments-api", environment="production", variables=[
        {
            "key": "DATABASE_URL",
            "value": "postgresql://user:pass@host:5432/db",
        },
        {
            "key": "LOG_LEVEL",
            "value": "debug",
            "kind": models.Kind.RECOVERABLE,
            "description": "Application log verbosity",
        },
    ], prune=True)

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.environments.setEnvironmentVariables({
    project: "payments",
    app: "payments-api",
    environment: "production",
    variables: [
      {
        key: "DATABASE_URL",
        value: "postgresql://user:pass@host:5432/db",
      },
      {
        key: "LOG_LEVEL",
        value: "debug",
        kind: "recoverable",
        description: "Application log verbosity",
      },
    ],
    prune: true,
  });

  console.log(result);
}

run();

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Environments.SetEnvironmentVariables(ctx, components.V2EnvironmentsSetEnvironmentVariablesRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
        Variables: []components.EnvironmentVariableInput{
            components.EnvironmentVariableInput{
                Key: "DATABASE_URL",
                Value: "postgresql://user:pass@host:5432/db",
            },
            components.EnvironmentVariableInput{
                Key: "LOG_LEVEL",
                Value: "debug",
                Kind: components.KindRecoverable.ToPointer(),
                Description: unkey.Pointer("Application log verbosity"),
            },
        },
        Prune: unkey.Pointer(true),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2EnvironmentsSetEnvironmentVariablesResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/environments.setEnvironmentVariables \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "environment": "production",
  "project": "payments",
  "prune": true,
  "variables": [
    {
      "key": "DATABASE_URL",
      "kind": "writeonly",
      "value": "postgresql://user:pass@host:5432/db"
    },
    {
      "description": "Application log verbosity",
      "key": "LOG_LEVEL",
      "kind": "recoverable",
      "value": "debug"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    environment: 'production',
    project: 'payments',
    prune: true,
    variables: [
      {
        key: 'DATABASE_URL',
        kind: 'writeonly',
        value: 'postgresql://user:pass@host:5432/db'
      },
      {
        description: 'Application log verbosity',
        key: 'LOG_LEVEL',
        kind: 'recoverable',
        value: 'debug'
      }
    ]
  })
};

fetch('https://api.unkey.com/v2/environments.setEnvironmentVariables', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/environments.setEnvironmentVariables",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'environment' => 'production',
    'project' => 'payments',
    'prune' => true,
    'variables' => [
        [
                'key' => 'DATABASE_URL',
                'kind' => 'writeonly',
                'value' => 'postgresql://user:pass@host:5432/db'
        ],
        [
                'description' => 'Application log verbosity',
                'key' => 'LOG_LEVEL',
                'kind' => 'recoverable',
                'value' => 'debug'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/environments.setEnvironmentVariables")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"prune\": true,\n  \"variables\": [\n    {\n      \"key\": \"DATABASE_URL\",\n      \"kind\": \"writeonly\",\n      \"value\": \"postgresql://user:pass@host:5432/db\"\n    },\n    {\n      \"description\": \"Application log verbosity\",\n      \"key\": \"LOG_LEVEL\",\n      \"kind\": \"recoverable\",\n      \"value\": \"debug\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/environments.setEnvironmentVariables")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"prune\": true,\n  \"variables\": [\n    {\n      \"key\": \"DATABASE_URL\",\n      \"kind\": \"writeonly\",\n      \"value\": \"postgresql://user:pass@host:5432/db\"\n    },\n    {\n      \"description\": \"Application log verbosity\",\n      \"key\": \"LOG_LEVEL\",\n      \"kind\": \"recoverable\",\n      \"value\": \"debug\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {}
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}