> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Secrets

> The secrets operations of the v1 API.

## List a cluster's secrets

`GET /v1/clusters/{cluster_id}/secrets` (operation ID `list_cluster_secrets`)

List a cluster's secrets (metadata only, never values).

Ordered by creation time, oldest first. Cursor paginated.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): Opaque cursor from the previous page's `next_cursor`.
- `limit` (query, `integer`): Page size, 1 to 100 (default 25).
- `cluster_id` (path, required, `string`): The cluster UUID

**Responses**

- `200`: A page of secrets. Body: [`V1Page_for_V1Secret`](/api/reference/schemas#v1page_for_v1secret).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Cluster not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/secrets' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Create a cluster secret

`POST /v1/clusters/{cluster_id}/secrets` (operation ID `create_cluster_secret`)

The value is write-only: it is never returned.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID

**Request body**: [`V1CreateSecret`](/api/reference/schemas#v1createsecret) (required): Create a secret. The value is stored encrypted and never returned.

**Responses**

- `201`: The created secret. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Invalid body or field.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (BILLING_ACCOUNT_BLOCKED): top up to create.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Cluster not found.
- `409`: A secret with this name already exists in the cluster.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X POST 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/secrets' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"example","value":"example"}'
```

## Get a cluster secret's metadata

`GET /v1/clusters/{cluster_id}/secrets/{secret_id}` (operation ID `get_cluster_secret`)

Get a cluster secret's metadata (never its value).

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `secret_id` (path, required, `string`): The secret UUID

**Responses**

- `200`: The secret. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Malformed id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Cluster or secret not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Delete a cluster secret

`DELETE /v1/clusters/{cluster_id}/secrets/{secret_id}` (operation ID `delete_cluster_secret`)

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `secret_id` (path, required, `string`): The secret UUID

**Responses**

- `204`: Deleted.
- `400`: Malformed id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Cluster or secret not found.
- `409`: The app the secret was created from is still running.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X DELETE 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Set a cluster secret's value

`PUT /v1/clusters/{cluster_id}/secrets/{secret_id}/value` (operation ID `set_cluster_secret_value`)

Set a cluster secret's value: it becomes the next version. The value is write-only: it is never returned.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cluster_id` (path, required, `string`): The cluster UUID
- `secret_id` (path, required, `string`): The secret UUID

**Request body**: [`V1SetSecretValue`](/api/reference/schemas#v1setsecretvalue) (required): A new value for a secret (write-only). It becomes the next version.

**Responses**

- `200`: The secret with its new version. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Invalid body, or the value does not fit the secret's file mounts.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (BILLING_ACCOUNT_BLOCKED): top up to create.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Cluster or secret not found.
- `409`: The value conflicts with the secret's file mounts.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X PUT 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002/value' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"value":"example"}'
```

## List an environment's secret groups

`GET /v1/environments/{environment_id}/secret-groups` (operation ID `list_secret_groups`)

Ordered by creation time, oldest first. Cursor paginated.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): Opaque cursor from the previous page's `next_cursor`.
- `limit` (query, `integer`): Page size, 1 to 100 (default 25).
- `environment_id` (path, required, `string`): The environment UUID

**Responses**

- `200`: A page of secret groups. Body: [`V1Page_for_V1SecretGroup`](/api/reference/schemas#v1page_for_v1secretgroup).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Environment not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secret-groups' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Create an empty secret group in the environment

`POST /v1/environments/{environment_id}/secret-groups` (operation ID `create_secret_group`)

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID

**Request body**: [`V1CreateSecretGroup`](/api/reference/schemas#v1createsecretgroup) (required): A new secret group (empty; add members afterwards).

**Responses**

- `201`: The created group. Body: [`V1SecretGroup`](/api/reference/schemas#v1secretgroup).
- `400`: Invalid body or name.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (BILLING_ACCOUNT_BLOCKED): top up to create.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Environment not found.
- `409`: A group with this name already exists in the environment.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X POST 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secret-groups' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"example"}'
```

## Get a secret group with its member secrets

`GET /v1/environments/{environment_id}/secret-groups/{group_id}` (operation ID `get_secret_group`)

Get a secret group with its member secrets (metadata only, never values).

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID
- `group_id` (path, required, `string`): The secret group UUID

**Responses**

- `200`: The group and its members. Body: [`V1SecretGroupDetail`](/api/reference/schemas#v1secretgroupdetail).
- `400`: Malformed id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Environment or group not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secret-groups/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Add secrets to a group

`POST /v1/environments/{environment_id}/secret-groups/{group_id}/members` (operation ID `add_secret_group_members`)

Secrets already in the group are skipped, so the call is safe to repeat.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID
- `group_id` (path, required, `string`): The secret group UUID

**Request body**: [`V1AddGroupMembers`](/api/reference/schemas#v1addgroupmembers) (required): Secrets to add to a group. Secrets already in it are skipped.

**Responses**

- `200`: How many secrets were added. Body: [`V1GroupMembersAdded`](/api/reference/schemas#v1groupmembersadded).
- `400`: Invalid body, empty list, or a secret this environment cannot inject.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Environment or group not found.
- `409`: A linked app would get two files on one path.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X POST 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secret-groups/00000000-0000-4000-8000-000000000002/members' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"secret_ids":[]}'
```

## List an environment's secrets and those of its clusters

`GET /v1/environments/{environment_id}/secrets` (operation ID `list_environment_secrets`)

List an environment's secrets and those of its clusters (metadata only, never values).

Ordered by creation time, oldest first. Cursor paginated.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `cursor` (query, `string`): Opaque cursor from the previous page's `next_cursor`.
- `limit` (query, `integer`): Page size, 1 to 100 (default 25).
- `environment_id` (path, required, `string`): The environment UUID

**Responses**

- `200`: A page of secrets. Body: [`V1Page_for_V1Secret`](/api/reference/schemas#v1page_for_v1secret).
- `400`: Invalid limit or cursor.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Environment not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secrets' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Create an environment secret

`POST /v1/environments/{environment_id}/secrets` (operation ID `create_environment_secret`)

The value is write-only: it is never returned.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID

**Request body**: [`V1CreateSecret`](/api/reference/schemas#v1createsecret) (required): Create a secret. The value is stored encrypted and never returned.

**Responses**

- `201`: The created secret. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Invalid body or field.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (BILLING_ACCOUNT_BLOCKED): top up to create.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Environment not found.
- `409`: A secret with this name already exists in the environment.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X POST 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secrets' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"name":"example","value":"example"}'
```

## Get the metadata of an environment secret or one of its clusters' secrets

`GET /v1/environments/{environment_id}/secrets/{secret_id}` (operation ID `get_environment_secret`)

Get the metadata of an environment secret or one of its clusters' secrets (never its value).

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID
- `secret_id` (path, required, `string`): The secret UUID

**Responses**

- `200`: The secret. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Malformed id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope does not allow this.
- `404`: Environment or secret not found.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Delete an environment secret

`DELETE /v1/environments/{environment_id}/secrets/{secret_id}` (operation ID `delete_environment_secret`)

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID
- `secret_id` (path, required, `string`): The secret UUID

**Responses**

- `204`: Deleted.
- `400`: Malformed id.
- `401`: Missing, invalid or revoked API key.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Environment or secret not found (cluster secrets are changed through their cluster).
- `409`: The app the secret was created from is still running.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X DELETE 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
```

## Set an environment secret's value

`PUT /v1/environments/{environment_id}/secrets/{secret_id}/value` (operation ID `set_environment_secret_value`)

Set an environment secret's value: it becomes the next version. The value is write-only: it is never returned.

Authentication: `api_key` ([how to authenticate](/api/authentication)).

**Parameters**

- `environment_id` (path, required, `string`): The environment UUID
- `secret_id` (path, required, `string`): The secret UUID

**Request body**: [`V1SetSecretValue`](/api/reference/schemas#v1setsecretvalue) (required): A new value for a secret (write-only). It becomes the next version.

**Responses**

- `200`: The secret with its new version. Body: [`V1Secret`](/api/reference/schemas#v1secret).
- `400`: Invalid body, or the value does not fit the secret's file mounts.
- `401`: Missing, invalid or revoked API key.
- `402`: The billing account is blocked (BILLING_ACCOUNT_BLOCKED): top up to create.
- `403`: The key's scope or the caller's role does not allow this.
- `404`: Environment or secret not found (cluster secrets are changed through their cluster).
- `409`: The value conflicts with the secret's file mounts.
- `429`: This API key spent its request budget for the current window (code `rate_limited`); retry after `Retry-After` seconds. Body: [`V1Error`](/api/reference/schemas#v1error).

```bash
curl -X PUT 'https://api.a-line.cloud/v1/environments/00000000-0000-4000-8000-000000000001/secrets/00000000-0000-4000-8000-000000000002/value' \
  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \
  -H 'Content-Type: application/json' \
  -d '{"value":"example"}'
```
