---
title: Secrets | Runware Docs
url: https://runware.ai/docs/serverless/api-secrets
description: Manage an environment's secrets and the attachments that expose them to an app.
relatedDocuments:
  - https://runware.ai/docs/serverless/api
  - https://runware.ai/docs/serverless/secrets
  - https://runware.ai/docs/serverless/environment-variables
---
## Introduction

A secret is **stored once in an environment and attached to the apps that need it**, so the two halves of this page are separate: the store belongs to the environment, and an attachment binds one secret to one app. Both halves take `environment`, and omitted it is `production`.

An attachment resolves to **the environment variable name the value is injected as**, which defaults to the secret's own name. That indirection is what lets the same code read `HF_TOKEN` against a production and a staging credential.

> [!NOTE]
> Secrets and plain environment variables share one pod environment and **one ceiling of 100 bindings per app**. A name already taken by either is rejected with `422`, and attaching a secret the app already has returns `409`. See [Secrets](https://runware.ai/docs/serverless/secrets).

## List secrets

GETapi.serverless.runware.ai/v1/secrets

Returns secret metadata only. Encrypted values are never returned.

### [Request](#list-secrets-request)

Query

### [environment](#list-secrets-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [limit](#list-secrets-query-limit)

- **Type**: `integer`
- **Format**: `int32`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of items to return.

### [cursor](#list-secrets-query-cursor)

- **Type**: `string`

Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the operations that offer one, `prevCursor`.

### [Response](#list-secrets-response)

### [nextCursor](#list-secrets-response-nextcursor)

- **Type**: `string (nullable)`

Cursor for the next page. Null when there are no more items.

### [data](#list-secrets-response-data)

- **Type**: `object[] (7 properties)`

#### [id](#list-secrets-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [environment](#list-secrets-response-data-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

#### [name](#list-secrets-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

#### [type](#list-secrets-response-data-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

#### [metadata](#list-secrets-response-data-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

#### [createdAt](#list-secrets-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [updatedAt](#list-secrets-response-data-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#list-secrets-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Create a secret

POSTapi.serverless.runware.ai/v1/secrets

Creates a secret in the environment named by `environment`, `production` when omitted. A secret of the same name in another environment is a different secret. To copy one into another environment, use `POST /v1/secrets/{secretName}/copy`. Returns `409` if the name is already in use in the environment, including when a secret of that name is `pending_destroy`. List only shows active secrets, so a name can appear free while create still conflicts for as long as that row remains. A `pending_destroy` row is removed, and its name released, by a background sweep once no running worker can still hold the value. There is no deadline on that wait, so a continuously busy app can hold a name for as long as it runs. Recreate-while-deleting may later reuse the pending row with the new value (same name, new ciphertext). An organization whose serverless tenancy is revoked, or has no tenancy receipt at all, returns `403 Forbidden`: the per-organization CryptoKey that seals the value is only minted when the tenancy is active. An organization whose tenancy is still being provisioned returns `503 Service Unavailable` instead. That state is retryable, not a revocation, and clears once provisioning finishes.

### [Request](#create-secret-request)

Query

### [environment](#create-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [name](#create-secret-body-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

### [type](#create-secret-body-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Allowed values**: `generic` `registry`

### [value](#create-secret-body-value)

- **Type**: `string`
- **Required**: true
- **Max**: `65536`

Plain-text value. Encrypted at rest by the platform. Capped at 64 KiB, Cloud KMS Encrypt's plaintext ceiling, and the reason the design needs no envelope encryption (ADR-019). `maxLength` is OpenAPI's string-length bound (character count), not a byte limit. Cloud KMS measures UTF-8 bytes, so the server also rejects a value whose UTF-8 encoding exceeds 65536 bytes with `422`, a rule this schema cannot express alone (multi-byte characters can pass `maxLength` and still overrun the KMS limit). A `registry` value is a Docker `config.json`; what that document may contain, and what `422` refuses, is on `SecretType`.

### [metadata](#create-secret-body-metadata)

- **Type**: `object (nullable)`

### [environments](#create-secret-body-environments)

- **Type**: `string[]`
- **Min items**: `1`
- **Max items**: `100`

The environments to create this secret in, one secret per environment, all with this value. Only on a `POST /v1/secret-batches` item, and only when the request does not name `environment`; then every item names its own. `POST /v1/secrets` returns `422` when it is set. An environment the organization does not have returns `404`, and nothing is created.

### [Response](#create-secret-response)

### [id](#create-secret-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [environment](#create-secret-response-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

### [name](#create-secret-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

### [type](#create-secret-response-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

### [metadata](#create-secret-response-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

### [createdAt](#create-secret-response-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [updatedAt](#create-secret-response-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#create-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Create many secrets

POSTapi.serverless.runware.ai/v1/secret-batches

Creates secrets in the environment named by `environment`, `production` when omitted. An item that names its own `environments` is created once in each of them instead, and then every item must name them and `environment` must be omitted (`422` otherwise). A name may appear in several items as long as no environment receives it twice. The batch is one write: every secret is created, or none are. Returns `409` when any name is already in use in an environment it is sent to, including when a secret of that name is `pending_destroy`, and `errors[]` names each conflicting item: its `name`, or the entry of its `environments` when the item names them. List only shows active secrets, so a name can appear free while create still conflicts for as long as that row remains. A `pending_destroy` row is removed, and its name released, by a background sweep once no running worker can still hold the value. There is no deadline on that wait, so a continuously busy app can hold a name for as long as it runs. A name sent twice to one environment is `422`. This route does not attach a secret to an app. Attach each one with `POST /v1/apps/{appId}/secrets`. An organization whose serverless tenancy is revoked, or has no tenancy receipt at all, returns `403 Forbidden`: the per-organization CryptoKey that seals the value is only minted when the tenancy is active. An organization whose tenancy is still being provisioned returns `503 Service Unavailable` instead. That state is retryable, not a revocation, and clears once provisioning finishes.

### [Request](#create-secret-batch-request)

Query

### [environment](#create-secret-batch-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [secrets](#create-secret-batch-body-secrets)

- **Type**: `object[] (5 properties)`
- **Required**: true
- **Min items**: `1`
- **Max items**: `100`

Secrets to create. The response lists them in this order, an item once per environment it names. At most 100, and at most 200 secrets written in all (`422` beyond that). The request body is still capped at 1 MiB, which is what limits how many large values fit. Each item has the same fields and the same 64 KiB value ceiling as `SecretCreate`.

#### [name](#create-secret-batch-body-secrets-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

#### [type](#create-secret-batch-body-secrets-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Allowed values**: `generic` `registry`

#### [value](#create-secret-batch-body-secrets-value)

- **Type**: `string`
- **Required**: true
- **Max**: `65536`

Plain-text value. Encrypted at rest by the platform. Capped at 64 KiB, Cloud KMS Encrypt's plaintext ceiling, and the reason the design needs no envelope encryption (ADR-019). `maxLength` is OpenAPI's string-length bound (character count), not a byte limit. Cloud KMS measures UTF-8 bytes, so the server also rejects a value whose UTF-8 encoding exceeds 65536 bytes with `422`, a rule this schema cannot express alone (multi-byte characters can pass `maxLength` and still overrun the KMS limit). A `registry` value is a Docker `config.json`; what that document may contain, and what `422` refuses, is on `SecretType`.

#### [metadata](#create-secret-batch-body-secrets-metadata)

- **Type**: `object (nullable)`

#### [environments](#create-secret-batch-body-secrets-environments)

- **Type**: `string[]`
- **Min items**: `1`
- **Max items**: `100`

The environments to create this secret in, one secret per environment, all with this value. Only on a `POST /v1/secret-batches` item, and only when the request does not name `environment`; then every item names its own. `POST /v1/secrets` returns `422` when it is set. An environment the organization does not have returns `404`, and nothing is created.

### [Response](#create-secret-batch-response)

### [data](#create-secret-batch-response-data)

- **Type**: `object[] (7 properties)`
- **Required**: true

#### [id](#create-secret-batch-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [environment](#create-secret-batch-response-data-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

#### [name](#create-secret-batch-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

#### [type](#create-secret-batch-response-data-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

#### [metadata](#create-secret-batch-response-data-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

#### [createdAt](#create-secret-batch-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [updatedAt](#create-secret-batch-response-data-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#create-secret-batch-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Update a secret

PUTapi.serverless.runware.ai/v1/secrets/{secretName}

Re-encrypts the value under the same name (no rename). A secret of the same name in another environment is not changed. Rolls every live deployment that attaches this secret in place so a running worker picks up the new value. `activeVersionId` does not move. See `AppEvent`. If a rollout is already in progress when this commits, this change is not guaranteed to land on it, so the deployment rolls again on its own once that rollout finishes, and records an event that says so. A deployment that is not live picks it up on its next deploy for another reason. An organization whose serverless tenancy is revoked, or has no tenancy receipt at all, returns `403 Forbidden`: the per-organization CryptoKey that seals the value is only minted when the tenancy is active. An organization whose tenancy is still being provisioned returns `503 Service Unavailable` instead. That state is retryable, not a revocation, and clears once provisioning finishes.

### [Request](#update-secret-request)

Path

### [secretName](#update-secret-path-secretname)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment (the one named by `environment` on `/v1/secrets`, `production` when omitted; the app's on an app route).

Query

### [environment](#update-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [value](#update-secret-body-value)

- **Type**: `string`
- **Required**: true
- **Max**: `65536`

Plain-text value. Encrypted at rest by the platform. Same 64 KiB Cloud KMS plaintext ceiling and UTF-8 byte check as `SecretCreate.value`.

### [metadata](#update-secret-body-metadata)

- **Type**: `object`

Omit to leave the stored metadata unchanged. Send an object (including `{}`) to replace it.

### [Response](#update-secret-response)

### [id](#update-secret-response-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

### [environment](#update-secret-response-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

### [name](#update-secret-response-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

### [type](#update-secret-response-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

### [metadata](#update-secret-response-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

### [createdAt](#update-secret-response-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [updatedAt](#update-secret-response-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#update-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Copy a secret to other environments

POSTapi.serverless.runware.ai/v1/secrets/{secretName}/copy

Creates a secret in each of `targetEnvironments` with the name, type, metadata and value of this secret. The value is copied inside the platform and never returned. Each copy is a separate secret: changing or deleting one leaves this secret and the other copies unchanged. The copy is one write: every target gets the secret, or none does. Returns `404` when the environment named by `environment` holds no active secret of this name, or when any of the environments does not exist. Returns `409` when the name is already in use in a target environment, including when a secret of that name is `pending_destroy`, and `errors[]` names each conflicting entry of `targetEnvironments`. Returns `422` when `targetEnvironments` includes the secret's own environment. This route does not attach a copy to an app. Attach each one with `POST /v1/apps/{appId}/secrets`. Like every secret write, it needs an active serverless tenancy: an organization whose tenancy is revoked, or has no tenancy receipt at all, returns `403 Forbidden`. An organization whose tenancy is still being provisioned returns `503 Service Unavailable` instead. That state is retryable, not a revocation, and clears once provisioning finishes.

### [Request](#copy-secret-request)

Path

### [secretName](#copy-secret-path-secretname)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment (the one named by `environment` on `/v1/secrets`, `production` when omitted; the app's on an app route).

Query

### [environment](#copy-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [targetEnvironments](#copy-secret-body-targetenvironments)

- **Type**: `string[]`
- **Required**: true
- **Min items**: `1`
- **Max items**: `100`

The environments to create a copy in, one secret in each.

### [Response](#copy-secret-response)

### [data](#copy-secret-response-data)

- **Type**: `object[] (7 properties)`
- **Required**: true

#### [id](#copy-secret-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [environment](#copy-secret-response-data-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

#### [name](#copy-secret-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

#### [type](#copy-secret-response-data-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

#### [metadata](#copy-secret-response-data-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

#### [createdAt](#copy-secret-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [updatedAt](#copy-secret-response-data-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

### [Errors](#copy-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Delete a secret

DELETEapi.serverless.runware.ai/v1/secrets/{secretName}

Soft-deletes a secret: marks the row `pending_destroy` and bumps revision. This API does not hard-delete the row. Returns `409` while any app still attaches it. Cascade-detach is not performed here. Detach each holder with `DELETE .../apps/{id}/secrets/{name}` first, which rolls the deployments it names in place. A background sweep removes the row and releases the name once no running worker can still hold the value, rather than assuming every roll a detach started actually landed. A deployment that was not live when detached has nothing to roll until it resumes, so the sweep is the actual backstop, not the detach. While the row remains `pending_destroy` the name stays reserved in the environment, so create may return `409` (already in use in the environment) even though list no longer shows the secret. Retries on an already-pending name are safe when no attachments remain (`204`). They still return `409` while attached.

### [Request](#delete-secret-request)

Path

### [secretName](#delete-secret-path-secretname)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment (the one named by `environment` on `/v1/secrets`, `production` when omitted; the app's on an app route).

Query

### [environment](#delete-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to. The same name in two environments is two secrets: a write to one never changes the other, and a list cursor is valid only in the environment it came from. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Errors](#delete-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## List an app's secrets

GETapi.serverless.runware.ai/v1/apps/{appId}/secrets

### [Request](#list-app-secrets-request)

Path

### [appId](#list-app-secrets-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

Query

### [environment](#list-app-secrets-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [limit](#list-app-secrets-query-limit)

- **Type**: `integer`
- **Format**: `int32`
- **Min**: `1`
- **Max**: `100`
- **Default**: `20`

Maximum number of items to return.

### [cursor](#list-app-secrets-query-cursor)

- **Type**: `string`

Opaque pagination cursor returned by a previous call, as `nextCursor` or, on the operations that offer one, `prevCursor`.

### [Response](#list-app-secrets-response)

### [nextCursor](#list-app-secrets-response-nextcursor)

- **Type**: `string (nullable)`

Cursor for the next page. Null when there are no more items.

### [data](#list-app-secrets-response-data)

- **Type**: `object[] (8 properties)`

#### [id](#list-app-secrets-response-data-id)

- **Type**: `string (uuid)`
- **Required**: true
- **Format**: `UUID v4`

#### [environment](#list-app-secrets-response-data-environment)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `63`

The environment the secret belongs to; set at creation and never changed.

#### [name](#list-app-secrets-response-data-name)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

#### [type](#list-app-secrets-response-data-type)

- **Type**: `string`
- **Required**: true

Kind of secret. `generic` is unsealed into the worker's process environment when the secret is attached to an app. `registry` is a Docker `config.json` whose only top-level key is `auths`. Each entry has `auth`, or `username` and `password`, or `identitytoken`. A value is `422` when it names `credHelpers` or `credsStore`, any other top-level key, an entry key other than `auth`, `username`, `password` or `identitytoken`, a key that is not a registry host (a host has a dot or a port, or is `localhost`), two keys that normalize to the same host, or a key that appears twice. The platform stores the ciphertext the same way as `generic` and keeps the normalized registry hosts beside it. A `registry` secret cannot be attached to an app (`422` `secret-not-attachable`).

**Possible values**: `generic` `registry`

#### [metadata](#list-app-secrets-response-data-metadata)

- **Type**: `object (nullable)`

Optional opaque metadata associated with the secret.

#### [createdAt](#list-app-secrets-response-data-createdat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [updatedAt](#list-app-secrets-response-data-updatedat)

- **Type**: `string (date-time)`
- **Format**: `date-time`

#### [envVarName](#list-app-secrets-response-data-envvarname)

- **Type**: `string (nullable)`
- **Min**: `1`
- **Max**: `128`

Resolved environment variable name when it differs from `name`. Omitted when the secret name is used. Same reserved-name rules as `SecretName` when set.

### [Errors](#list-app-secrets-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Attach a secret to an app

POSTapi.serverless.runware.ai/v1/apps/{appId}/secrets

Records that a secret of the app's environment is attached to the app under a resolved env-var name, and rolls the app's live deployment in place so a running worker picks up the value without waiting for an unrelated deploy. `activeVersionId` does not move. See `AppEvent`. If a rollout is already in progress when this commits, this attach is not guaranteed to land on it, so the deployment rolls again on its own once that rollout finishes, and records an event that says so. A deployment that is not live records the attachment only. The next resume reads the attach set fresh. Returns `409` if the secret is already attached, or if another attach would use the same env-var name. The resolved name (`envVarName`, or `secretName` when omitted) must not already exist as a plain environment variable on this app (`deployment_configs.key`). Only one value can reach the app under a name, so the server rejects the collision with `422` instead of letting one value silently shadow the other. The reverse check applies when setting a plain environment variable. An app holds at most 100 environment bindings in total, plain environment variables plus attached secrets, the same combined ceiling as create and the single-key env-var route. Attaching when the app is already at that limit returns `422`. A secret can be attached to at most 25 deployments. Rolling every attached deployment is what an update or detach costs, so the ceiling bounds that cost rather than the app side of the binding. Attaching past it returns `422`. A `registry` secret returns `422` `secret-not-attachable`: a registry login is not an environment variable.

### [Request](#attach-app-secret-request)

Path

### [appId](#attach-app-secret-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

Query

### [environment](#attach-app-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

Body

### [secretName](#attach-app-secret-body-secretname)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment. The shape matches `EnvironmentVariableName` and the `secrets.name` / `deployment_secrets.env_var_name` column CHECKs, one rule for the contract and the schema, because an attached secret is injected as an environment variable under this name, or under `envVarName` when that override is set. Names the platform sets in the worker's environment (for example `RUNTIME`, `DISABLE_NGINX`, `MLFLOW_MODELS_WORKERS`, `UVICORN_HOST`) are rejected with `422`: an accepted collision would replace a platform value the app depends on, be silently dropped in its favour, or reach the app under a name the platform uses for its own value, with no error anywhere. Same guard as plain environment variables. Enforced by the server (not expressible as a pattern here).

### [envVarName](#attach-app-secret-body-envvarname)

- **Type**: `string (nullable)`
- **Min**: `1`
- **Max**: `128`

Environment variable name the secret is injected as. Omit or null to use `secretName`. The server resolves and stores the final name. Same reserved-name rules as `SecretName` (`422` if reserved). The resolved name must also not collide with a plain environment variable key on this app (`422`).

### [Errors](#attach-app-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">400</code></td><td data-rw-cid-pz7tphoj="true">The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns <code class="component-Code">422</code> instead.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">409</code></td><td data-rw-cid-pz7tphoj="true">Resource already exists or the request conflicts with its current state</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">413</code></td><td data-rw-cid-pz7tphoj="true">The request body exceeds its size limit: 10 MiB on <code class="component-Code">invoke-sync</code> and <code class="component-Code">invoke-async</code>, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. <code class="component-Code">detail</code> names the limit in bytes.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">415</code></td><td data-rw-cid-pz7tphoj="true">The request body arrived with a Content-Type this operation does not accept. The body was not decoded, so this is not a schema failure. A body of <code class="component-Code">application/json</code> that cannot be parsed returns <code class="component-Code">400</code>. One that parses and breaks the schema returns <code class="component-Code">422</code>. A body sent with no Content-Type is the same refusal.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but invalid. A field that broke a rule is <code class="component-Code">unprocessable-entity</code>. Attaching a <code class="component-Code">registry</code> secret is <code class="component-Code">secret-not-attachable</code>. A request that could not be parsed returns <code class="component-Code">400</code>.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>

## Detach a secret from an app

DELETEapi.serverless.runware.ai/v1/apps/{appId}/secrets/{secretName}

Removes the attachment and rolls the app's live deployment in place so a running worker stops receiving the value. `activeVersionId` does not move. See `AppEvent`. If a rollout is already in progress when this commits, this detach is not guaranteed to land on it, so the deployment rolls again on its own once that rollout finishes, and records an event that says so. A deployment that is not live has the removal recorded only. There is nothing to roll until it resumes.

### [Request](#detach-app-secret-request)

Path

### [appId](#detach-app-secret-path-appid)

- **Type**: `string`
- **Required**: true
- **Min**: `6`
- **Max**: `30`

Immutable app identifier, unique among the authenticated organization's live apps in one environment. The `environment` query parameter selects which copy the request addresses.

### [secretName](#detach-app-secret-path-secretname)

- **Type**: `string`
- **Required**: true
- **Min**: `1`
- **Max**: `128`

Secret name, unique within an environment (the one named by `environment` on `/v1/secrets`, `production` when omitted; the app's on an app route).

Query

### [environment](#detach-app-secret-query-environment)

- **Type**: `string`
- **Min**: `1`
- **Max**: `63`

The environment the request addresses. An app id names one copy per environment, so this parameter completes the app's address: `appId` together with `environment` selects the copy. The app list and the app summary are limited to the environment, and an app, build, endpoint, worker, event, usage or attached-secret cursor is valid only in the environment it came from. A metric query that names no app covers the whole organization, and a log query covers this environment; a metric query expanded by app returns only the apps live in this environment. Omitted means `production`. A name the organization has no live environment under returns `404`.

### [Errors](#detach-app-secret-errors)

<table><tbody><tr><td data-rw-cid-pz7tphoj="true">Status</td><td data-rw-cid-pz7tphoj="true">When</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">401</code></td><td data-rw-cid-pz7tphoj="true">Missing or invalid credentials</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">403</code></td><td data-rw-cid-pz7tphoj="true">Authenticated but not permitted to access this resource</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">404</code></td><td data-rw-cid-pz7tphoj="true">Resource not found</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">422</code></td><td data-rw-cid-pz7tphoj="true">The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns <code class="component-Code">400</code>. The <code class="component-Code">errors</code> array carries one entry per offending field.</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">500</code></td><td data-rw-cid-pz7tphoj="true">Unexpected server error</td></tr><tr><td data-rw-cid-pz7tphoj="true"><code data-rw-cid-pz7tphoj="">503</code></td><td data-rw-cid-pz7tphoj="true">A required service is temporarily unavailable</td></tr></tbody></table>