Docs menu
Docs/Developer interfaces/REST API/Secrets
View as Markdown

Secrets

Manage site runtime secrets and audit explicit value retrievals.

Method Operation Path
GET List secrets /v0/sites/:siteId/secrets
GET Get a secret value /v0/sites/:siteId/secrets/:name
GET List secret access logs /v0/sites/:siteId/secret_access_logs
POST Create a secret /v0/sites/:siteId/secrets
POST Update a secret /v0/sites/:siteId/secrets/:name
DELETE 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

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

Response

{
  "secrets": [{ "name": "API_TOKEN", "updatedAt": "2026-09-20T12:00:00.000Z" }],
  "pagination": { "hasMore": false, "nextOffset": null }
}
  • CLI: interfold secrets list --site <site-id>
  • MCP: list_secrets

See Errors for the standard error envelope and 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

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

Response

{
  "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.
  • CLI: interfold secrets get API_TOKEN --site <site-id>

See Errors for the standard error envelope and 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

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

Response

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

See Errors for the standard error envelope and 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

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

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

Behavior and errors

  • Responses never echo the supplied value.
  • CLI: printf %s "$API_TOKEN" | interfold secrets set API_TOKEN --site <site-id>
  • MCP: set_secret

See Errors for the standard error envelope and 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

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

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

Behavior and errors

  • Responses never echo the supplied value.
  • CLI: printf %s "$API_TOKEN" | interfold secrets set API_TOKEN --site <site-id>
  • MCP: set_secret

See Errors for the standard error envelope and 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

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

Response

{
  "deleted": true
}

Behavior and errors

  • Existing functions or cron jobs may fail until the secret is restored.
  • CLI: interfold secrets rm API_TOKEN --site <site-id>
  • MCP: delete_secret

See Errors for the standard error envelope and Authentication for API key handling.

Shared behavior

All operations use the API authentication, error, and rate-limit contracts. List operations use standard pagination unless the operation says otherwise.

On this page