# ESO

External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.

Source: https://keyenv.dev/docs/api/eso/

External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.
These endpoints allow ESO to fetch secrets from KeyEnv and sync them to Kubernetes Secrets.

**Authentication:** Service token required (user authentication not supported).

See the [Kubernetes ESO Integration Guide](https://docs.keyenv.dev/integrations/kubernetes-eso) for setup instructions.

## Get single secret for ESO

```http
GET /api/v1/eso/secret
```

Fetches a single secret value for External Secrets Operator webhook integration.

This endpoint is designed for ESO's webhook provider to fetch individual secrets.
The environment can be specified by name or ID.

**Authentication:** Only service token authentication is supported. User authentication
will return 403 Forbidden.

**Environment Inheritance:** If the secret is not found in the specified environment,
the inheritance chain is searched (child environments inherit from parents).

**Operation ID:** `getESOSecret` &middot; **Authentication:** `Authorization: Bearer <token>`

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | `string` | yes | Project ID or slug |
| `env` | `string` | yes | Environment name or ID |
| `key` | `string` | yes | Secret key name |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | Secret value retrieved successfully | `ESOSecretResponse` |
| `400` | Bad request. Possible causes: - Missing required query parameters (project, env, key) - Circular environment inheritance detected | `Error` |
| `401` | Authentication required or invalid token | `Error` |
| `403` | Forbidden. Possible causes: - Service token does not have access to this project - User authentication was used (ESO requires service token) | `Error` |
| `404` | Not found. Possible causes: - Project not found - Environment not found - Secret not found (including in inherited environments) | `Error` |
| `500` | Internal server error (e.g., decryption failure) | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `value` | `string` | The decrypted secret value |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/eso/secret" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```

## Get all secrets for ESO dataFrom

```http
GET /api/v1/eso/secrets
```

Fetches all secrets as a key-value map for External Secrets Operator's `dataFrom` feature.

This endpoint is designed for ESO's webhook provider to bulk-fetch all secrets from
an environment. The environment can be specified by name or ID.

**Authentication:** Only service token authentication is supported. User authentication
will return 403 Forbidden.

**Environment Inheritance:** Secrets are resolved through the inheritance chain.
Child environment values override parent values for the same key.

**Hidden Secrets:** Secrets that have been explicitly hidden (overridden with no value)
in the target environment are excluded from the response.

**Operation ID:** `getESOSecrets` &middot; **Authentication:** `Authorization: Bearer <token>`

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | `string` | yes | Project ID or slug |
| `env` | `string` | yes | Environment name or ID |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | All secrets retrieved successfully | `ESOSecretsResponse` |
| `400` | Bad request. Possible causes: - Missing required query parameters (project, env) - Circular environment inheritance detected | `Error` |
| `401` | Authentication required or invalid token | `Error` |
| `403` | Forbidden. Possible causes: - Service token does not have access to this project - User authentication was used (ESO requires service token) | `Error` |
| `404` | Not found. Possible causes: - Project not found - Environment not found | `Error` |
| `500` | Internal server error (e.g., decryption failure) | `Error` |

### Response body (`200`)

| Field | Type | Description |
| --- | --- | --- |
| `secrets` | `object` | Key-value map of all secrets in the environment |

### Example

```bash
curl -X GET "https://api.keyenv.dev/api/v1/eso/secrets" \
  -H "Authorization: Bearer $KEYENV_TOKEN"
```