> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and registries

> Keep credentials out of code and pull private images

Secrets, secret sets and registry connections belong to your organization. **Their values are write-only**: you send them on create or update, and the API never returns them.

## Secrets

A secret is a named value. Bind it to an environment variable in a [template](https://docs.bonya.ai/concepts/templates.md) with `secret_bindings`.

| Endpoint | Description |
| - | - |
| `GET /v1/secrets` | List secrets (names and ids only). |
| `POST /v1/secrets` | Create a secret. |
| `PATCH /v1/secrets/{secret_id}` | Update a secret. |
| `DELETE /v1/secrets/{secret_id}` | Delete a secret. |

```ts TypeScript theme={null}
await client.createSecret("DB_PASSWORD", "s3cret");
```

```python Python theme={null}
client.create_secret("DB_PASSWORD", "s3cret")
```

**MCP:** `secret_list`, `secret_create`, `secret_update`, `secret_delete`.

## Secret sets

A secret set is a named group of environment variables. Inject one into a sandbox, template or job with `secret_sets`.

> [!WARNING]
>
> Reference secret sets by **name**, not id. Using an id returns `404`.

| Endpoint | Description |
| - | - |
| `GET /v1/secret-sets` | List secret sets. |
| `POST /v1/secret-sets` | Create one with `name` and `values`. |
| `GET /v1/secret-sets/{secret_set_id}` | Get one (variable names, never values). |
| `PATCH /v1/secret-sets/{secret_set_id}` | Update its values. |
| `DELETE /v1/secret-sets/{secret_set_id}` | Delete it. |

```ts TypeScript theme={null}
await client.createSecretSet({ name: "app-env", values: { API_URL: "https://example.com" } });
const sandbox = await client.createSandbox({ secretSets: ["app-env"] });
```

```python Python theme={null}
client.create_secret_set("app-env", {"API_URL": "https://example.com"})
sandbox = client.create_sandbox(secret_sets=["app-env"])
```

**MCP:** `secret_set_list`, `secret_set_get`, `secret_set_create`, `secret_set_update`, `secret_set_delete`.

## Registry connections

A registry connection stores credentials for pulling private container images.

| Endpoint | Description |
| - | - |
| `GET /v1/registry-connections` | List connections (passwords are never returned). |
| `POST /v1/registry-connections` | Create one with `name`, `registry`, `username`, `password`. |
| `PATCH /v1/registry-connections/{connection_id}` | Update it. |
| `DELETE /v1/registry-connections/{connection_id}` | Delete it. |
| `POST /v1/registry-connections/{connection_id}/validate` | Check that an image can be pulled with it. |

```ts TypeScript theme={null}
const conn = await client.createRegistryConnection({
  name: "ghcr", registry: "ghcr.io", username: "me", password: "<token>",
});
await client.validateRegistryConnection(conn.id, "ghcr.io/me/app:latest");
```

```python Python theme={null}
conn = client.create_registry_connection("ghcr", "ghcr.io", "me", "<token>")
client.validate_registry_connection(conn.id, "ghcr.io/me/app:latest")
```

Reference the connection from a template with `registry_connection_id`. **MCP:** `registry_connection_list`, `registry_connection_create`, `registry_connection_update`, `registry_connection_delete`, `registry_connection_validate`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.