Skip to main content

Secrets and scopes

Secrets have a dedicated public surface because they should not be treated like normal file content.

Secret routes​

Key routes:

  • GET /v1/sessions/{sessionId}/secrets
  • GET /v1/sessions/{sessionId}/secrets/{secretName}
  • PUT /v1/sessions/{sessionId}/secrets/{secretName}
  • DELETE /v1/sessions/{sessionId}/secrets/{secretName}

Secret scopes​

The public contract exposes scopes such as:

  • session
  • tenant
  • unscoped

Use the narrowest scope that matches the workflow.

Handling guidance​

Do:

  • keep secret values out of logs
  • keep secret values out of annotations
  • keep secret values out of ordinary files unless the workflow explicitly requires it

Do not:

  • use secrets as generic config storage
  • treat the mounted filesystem as the default location for secrets

Secret names versus secret values​

Listing secrets is primarily about discovering which names are available.

Getting a secret is for the narrow case where a workflow actually needs the value.

That distinction helps products expose less sensitive information by default.