Paths and naming

Secret paths and naming

In Secrets Manager, the path is the identity of a secret. This page covers path rules, naming conventions, and how to list secrets.

Path rules

Rule	Value
Must start with	`/`
Length	1–512 characters
Allowed characters	`A–Z`, `a–z`, `0–9`, `/`, `_`, `-`, `.`, `+`
Trailing `/`	Not allowed (except browse root uses `/`)
Double slashes (`//`)	Not allowed

Valid and invalid examples

Path	Valid?
`/app/production/db/password`	✓
`/infra/vpn/tls-cert`	✓
`/app/production/`	✗ (trailing slash)
`app/production`	✗ (missing leading slash)
`/app//production/db`	✗ (double slash)

Naming conventions

Adopt a consistent hierarchy early. Paths are immutable identities — you cannot rename a secret without deleting and recreating it at a new path.

A common pattern:

/app/{environment}/{service}/{name}

Examples:

Path	Purpose
`/app/production/api/stripe-key`	Production API key
`/app/staging/db/credentials`	Staging database credentials
`/infra/vpn/tls-cert`	VPN TLS certificate
`/ci/github/deploy-token`	CI/CD deploy token

Separate environments and services in the path hierarchy. This makes IAM path-scoped policies straightforward: grant /app/production/* to production workloads and /app/staging/* to staging workloads.

Browse one directory level

Use browse for console-style navigation and interactive exploration:

GET /v1/secrets/{region}/secrets?path=/app/production/

Returns one directory level at a time:

Field	Description
`prefixes`	Child directories containing secrets the caller can read
`secrets`	Metadata for secrets stored directly at that path level

Drill down by changing path until you reach the leaf secret. Browse root uses path=/.

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  "https://api.thalassa.cloud/v1/secrets/nl-01/secrets?path=/app/production/"

Flat recursive list

Use flat list for search, export, and automation:

GET /v1/secrets/{region}/secrets?pathPrefix=/app/

Returns all secret metadata under the prefix. Results are filtered to paths where the caller has read permission.

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  "https://api.thalassa.cloud/v1/secrets/nl-01/secrets?pathPrefix=/app/"

Get single secret metadata

GET /v1/secrets/{region}/secret/app/production/db/password

The path can be embedded in the URL (preferred for automation) or passed as ?path=/app/production/db/password.

Add ?includeVersions=true to return version history (status, timestamps, valueFormat) without secret values.

IAM and paths

Paths are the IAM resource identity for secrets. Bind roles or policies on resource type secret with resourceIdentities set to specific paths. See Access control for permission details.

Even with list permission, browse and flat list results only include paths where the caller also has read.