For AI agents: markdown of this page — /docs-content-en/applications/app-secrets.md documentation index — /llms.txt
Application secrets
Secrets store an application's tokens and passwords: the value is set on the application card, and the platform passes it to the running application as an environment variable.
A value set on the card never passes through a conversation with an AI agent and is not sent in a deploy call. If the feature is not enabled for the Bitrix24 account, the card has no "Secrets" block and the methods below return 404 APPLICATION_NOT_FOUND.
Authorization: X-Api-Key. The methods can be called by the application owner with any of their keys, by the application's own key, and by members of the linked server's development team. Through the API and MCP you can list names, create names and delete them. Only the owner and the Bitrix24 account administrator set and replace values, on the /applications card. The API and MCP never accept or return a value. The dashboard does not show it after saving either: a value can only be replaced. The card's secrets history records when and by whom a name was created or a value was set, replaced or deleted, and how applying the change ended. The history contains no values.
How secrets reach the application
The application receives secrets as environment variables of its process and reads them the same way as variables from env: moving a value from env to a secret needs no change to the application code. A name without a value is not passed to the application.
On a standalone server, the platform writes the values to /var/lib/vibe/app-secrets/<service>.env and attaches the file to the application's systemd service. In Galaxy, the values are added to the container's environment when the container starts, not when the image is built. Details, including systemd: false, are in the "Application secrets" section of Full application deploy.
On deploy
Every deploy passes the current set of secrets to the application.
- A secret with a value takes precedence over a variable with the same name in the deploy's
env. The application receives the secret's value, andwarningsin the deploy response reports that theenvvalue was not applied. - A name without a value does not override
env: if the variable is passed inenv, the application receives it.warningsasks for the value to be set, with a link to the card. - The platform sets
PORT. The namesPORT,VIBE_*andHERMES_EVENT_INGEST_*cannot be secrets. - The
installandpreStartcommands, and in Galaxy the image build, do not receive secrets: the values exist only in the running application's environment. If a migration needs a secret, run it from the application itself at startup. - In Galaxy, a name that was previously delivered as a secret and then deleted reaches the container empty, even if the deploy's
envpasses it. This keeps the old value from coming back from an image. To pass that variable throughenvagain, create the name without a value.
Without a deploy
Saving a value on the card and deleting a secret take effect on their own, with no deploy. After "Save" or a deletion, the platform restarts the running application in the background with the new environment. On a standalone server the application's service restarts; in Galaxy the container is recreated from the current image. The application does not respond while it restarts. Creating a name without a value applies nothing.
On a standalone server, the platform records the application's service on every successful deploy, even if the application has no secrets yet. An application last deployed before the feature was enabled for the Bitrix24 account does not receive the first change: the card shows "Could not apply: the application needs to be redeployed" with a hint. Deploy once: the change applies during that deploy, and later changes apply without one.
Sleeping machine
A change does not wake the machine. While it sleeps, the card shows "Will apply when the machine wakes up", and status in the API is PENDING. After the machine wakes up, the platform applies the current set on its own. In Galaxy, the container is recreated with the new environment on wake. A standalone server first starts the application with the old values and restarts it once the server is back in contact with the platform.
Failure and retry
If applying fails, the card shows "Could not apply" with the reason, status in the API is FAILED, and the reason is in failureCode. While the machine is running, the platform retries on its own, at most once a minute. The "Retry" button on the card starts an attempt right away. It is available to the owner and the Bitrix24 account administrator. The API has no separate retry method. The exception is the reason SECRET_SERVICE_UNKNOWN: a retry cannot fix it without a deploy, so the platform does not retry on its own and the card has no "Retry" button.
failureCode |
Card label | What happened |
|---|---|---|
SECRET_SERVICE_UNKNOWN |
the application needs to be redeployed | Standalone server: the platform does not know the application's service yet because the application has not been deployed since secrets were enabled. Deploy the application, and the change applies during the deploy. |
SECRET_INVALID_SERVICE |
application service is not configured | Standalone server: the stored service name is not valid. Deploy the application. |
SECRET_RESTART_FAILED |
application restart failed | Standalone server: the service did not start with the new environment. |
SECRET_CONTAINER_UNAVAILABLE |
container is unavailable | Galaxy: the platform could not prepare to recreate the container. |
SECRET_RECREATE_FAILED |
application restart failed | Galaxy: the new container did not start. |
SECRET_DELIVERY_FAILED |
delivery failed | The values could not be delivered to the machine, including when the deploy that was delivering them failed. |
Migration and restore
Secrets belong to the application card, not to the machine. A redeploy and a migration of the application to another galaxy keep them: the application receives the current set again.
A restore from a backup takes the current values from the card, not the values as of the backup date. A restored machine receives the set again. When a container is restored into a new application, secrets are copied from the source application's card if that application still exists and both applications have the same owner and the same Bitrix24 account. Otherwise, set the secrets on the new application's card.
Protection boundaries
The dashboard, the API and MCP never return a value. It is not in the secrets history, the audit log or the deploy step output. However, the running application's environment and the secrets file can be read by anyone who runs commands on the machine: a development team member, an AI agent calling POST /exec, the install and preStart commands. The application's own code sees its environment variables. Secrets keep a value out of conversations and out of the API, but they do not hide it from anyone with access to the machine. Grant that access only to people allowed to know the values.
A secret does not revoke access in the external system. If a value leaks, change it in the external system, then replace the secret on the card. A deleted value can remain in older backups of the machine or the container.