# Secrets

Manage site runtime secrets and audit explicit value retrievals.

| Method | Operation | Path |
| --- | --- | --- |
| **`GET`** | [List secrets](#list-secrets) | `/v0/sites/:siteId/secrets` |
| **`GET`** | [Get a secret value](#get-a-secret-value) | `/v0/sites/:siteId/secrets/:name` |
| **`GET`** | [List secret access logs](#list-secret-access-logs) | `/v0/sites/:siteId/secret_access_logs` |
| **`POST`** | [Create a secret](#create-a-secret) | `/v0/sites/:siteId/secrets` |
| **`POST`** | [Update a secret](#update-a-secret) | `/v0/sites/:siteId/secrets/:name` |
| **`DELETE`** | [Delete a secret](#delete-a-secret) | `/v0/sites/:siteId/secrets/:name` |

## List secrets

List secret names and metadata without values.

**`GET`** `/v0/sites/:siteId/secrets`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/secrets" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "secrets": [{ "name": "API_TOKEN", "updatedAt": "2026-09-20T12:00:00.000Z" }],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

### Related interfaces

- **CLI:** `interfold secrets list --site <site-id>`
- **MCP:** `list_secrets`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Get a secret value

Retrieve a secret value and record an access-log entry.

**`GET`** `/v0/sites/:siteId/secrets/:name`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `name` — secret name.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/secrets/<name>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "secret": {
    "name": "API_TOKEN",
    "value": "<secret-value>"
  }
}
~~~

### Behavior and errors

- Read-only keys can retrieve values. Treat them as sensitive credentials.
- Prefer metadata listing when you only need to verify that a secret exists.
- MCP intentionally has no secret-value tool.

### Related interfaces

- **CLI:** `interfold secrets get API_TOKEN --site <site-id>`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## List secret access logs

List audited dashboard, CLI, and API secret-value retrievals.

**`GET`** `/v0/sites/:siteId/secret_access_logs`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>/secret_access_logs" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "accessLogs": [],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Create a secret

Create or replace a named secret.

**`POST`** `/v0/sites/:siteId/secrets`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID.
- `name` — secret name.
- `value` — secret value.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/secrets" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "name": "API_TOKEN",  "value": "<secret-value>"}'
~~~

### Response

~~~json
{
  "secret": { "name": "API_TOKEN", "updatedAt": "2026-09-20T12:00:00.000Z" }
}
~~~

### Behavior and errors

- Responses never echo the supplied value.

### Related interfaces

- **CLI:** `printf %s "$API_TOKEN" | interfold secrets set API_TOKEN --site <site-id>`
- **MCP:** `set_secret`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Update a secret

Replace a named secret value.

**`POST`** `/v0/sites/:siteId/secrets/:name`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID.
- `name` — secret name.
- `value` — replacement value.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>/secrets/<name>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "value": "<replacement-value>"}'
~~~

### Response

~~~json
{
  "secret": { "name": "API_TOKEN", "updatedAt": "2026-09-20T12:00:00.000Z" }
}
~~~

### Behavior and errors

- Responses never echo the supplied value.

### Related interfaces

- **CLI:** `printf %s "$API_TOKEN" | interfold secrets set API_TOKEN --site <site-id>`
- **MCP:** `set_secret`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Delete a secret

Delete a named secret.

**`DELETE`** `/v0/sites/:siteId/secrets/:name`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID.
- `name` — secret name.

### Request

~~~sh
curl -X DELETE \
  "https://api.interfold.dev/v0/sites/<site-id>/secrets/<name>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "deleted": true
}
~~~

### Behavior and errors

- Existing functions or cron jobs may fail until the secret is restored.

### Related interfaces

- **CLI:** `interfold secrets rm API_TOKEN --site <site-id>`
- **MCP:** `delete_secret`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

## Shared behavior

All operations use the [API authentication](/api-reference/authentication),
[error](/api-reference/errors), and [rate-limit](/api-reference/rate-limits)
contracts. List operations use [standard pagination](/api-reference/pagination)
unless the operation says otherwise.