---
topic: env-vars
connector: "update_app · set_env_vars / apply_env_vars; app_danger_zone · delete_env_var; read_app · env_vars"
api: "https://ship.embarko.ai/api/apps/{app-name}/env-vars"
needs_human: "Only when a value is something only they have, such as their own API key."
requires: [claim]
---

[← Guide home](https://embarko.ai/docs)

# Secrets and settings

**On this page:** With the connector, Over HTTP, Examples, Limits, Errors, What to tell the person

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites) Needs first: [claim](https://embarko.ai/docs/claim) (over HTTP only).

Environment variables for one app. Values are write-only: you can list the keys, never read a value back.

**Connector:** update_app · set_env_vars / apply_env_vars; app_danger_zone · delete_env_var; read_app · env_vars

**Done when:** The feature that needs the value works.

**With the connector**

1. Call update_app { action: "set_env_vars", appName, vars: [{ key, value }], apply: true }.
2. If the person must type a secret themselves, give them the secrets page, https://embarko.ai/app/projects/{project-id}/environment, rather than asking them to paste it into the chat. {project-id} is the id field of GET https://ship.embarko.ai/api/apps/{app-name}. If they already pasted a key in the chat, use it and suggest they rotate it later.

**Over HTTP**

1. PUT https://ship.embarko.ai/api/apps/{app-name}/env-vars with the token and the body in the example below. It merges: keys you leave out stay as they are.
2. If the person already pasted a key in the chat, use it and suggest they replace it with a new one later.
3. One key: PUT https://ship.embarko.ai/api/apps/{app-name}/env-vars/{KEY} with {"value": "...", "apply": true}.
4. Without "apply": true the value is only stored: POST https://ship.embarko.ai/api/apps/{app-name}/env-vars/apply (or redeploy).
5. Order: if the code that reads the key is not deployed yet, store the value without apply, then deploy the new code (a deploy picks up stored values). If the code is already live, set it with apply.
6. Send X-Agent-Name on any call that applies.

**Example: Set two values and apply them**

body.json:

```json
{"vars":[{"key":"OPENAI_API_KEY","value":"sk-..."},{"key":"NOTIFY_EMAIL","value":"sam@example.com"}],"apply":true}
```

```bash
curl -sS -X PUT 'https://ship.embarko.ai/api/apps/my-app/env-vars' --oauth2-bearer $DEPLOY_TOKEN -H 'X-Agent-Name: {your-name}' -H 'Content-Type: application/json' --data @body.json
```

**Limits**

- Keys match ^[A-Za-z_][A-Za-z0-9_]*$.
- PORT, APP_NAME, APP_VERSION and DATA_DIR are set by Embarko.
- Static sites have no env vars (409 not_supported_for_static).
- Over HTTP, the app must be claimed.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `not_supported_for_static` | 409 | No | Static site: put config in its files, or redeploy as a server app under a new name. |
| `no_current_deployment` | 422 | No | Values are saved. Deploy the app; do not write them again. |
| `unauthorized` | 401 | No | Bad token. |

**What to tell the person**

- missing: "Your app needs a key before it can work. Add it here: {secrets page link}"

**Next:** Set the variables with apply, then check the app still works.

**Related:** [status](https://embarko.ai/docs/status) · [logs](https://embarko.ai/docs/logs)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json