Secrets API

Store sensitive values and registry credentials. See Secrets for the conceptual model.

Key/value secrets

Endpoints

Method	Path	Description
POST	/secrets	Create a secret
GET	/secrets	List secrets (names only)
PUT	/secrets	Update a secret (requires id)
DELETE	/secrets/{id}	Delete a secret

The secret object

{
  "id": "…",
  "project_id": "…",
  "name": "api-key"
}

The value is write-only — it’s never returned by the API.

Create a secret

The value must be base64-encoded:

# Encode
echo -n "sk_live_1234567890abcdef" | base64
# c2tfbGl2ZV8xMjM0NTY3ODkwYWJjZGVm

curl -X POST https://api.cumin.dev/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "…", "name": "api-key", "value": "c2tfbGl2ZV8xMjM0NTY3ODkwYWJjZGVm" }'

Response:

{ "id": "…" }

List secrets

curl https://api.cumin.dev/secrets \
  -H "Authorization: Bearer $TOKEN"

Returns each secret’s id and name — never the value.

Update a secret

curl -X PUT https://api.cumin.dev/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "<secret-id>", "name": "api-key", "value": "<new-base64-value>" }'

Delete a secret

curl -X DELETE https://api.cumin.dev/secrets/<secret-id> \
  -H "Authorization: Bearer $TOKEN"

Pull secrets (registry credentials)

Endpoints

Method	Path	Description
POST	/secrets/pull	Create a pull secret
GET	/secrets/pull	List pull secrets
PUT	/secrets/pull	Update a pull secret (requires id)
DELETE	/secrets/pull/{id}	Delete a pull secret

The pull secret object

{
  "id": "…",
  "project_id": "…",
  "server": "https://index.docker.io/v1/",
  "username": "your-docker-user",
  "created_at": 1720000000,
  "updated_at": 1720000123
}

The password is write-only and never returned.

Create a pull secret

curl -X POST https://api.cumin.dev/secrets/pull \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "…",
    "server": "https://index.docker.io/v1/",
    "username": "your-docker-user",
    "password": "your-docker-token"
  }'

Registry reference

The server, username, and password you send depend on the registry:

Registry	server	username	password
Docker Hub	https://index.docker.io/v1/	Docker Hub username	Access token (not your password)
GitHub Container Registry	https://ghcr.io	GitHub username	PAT with read:packages
GitLab Container Registry	https://registry.gitlab.com	GitLab username	PAT with read_registry
Google Artifact Registry	https://gcr.io	oauth2accesstoken / _json_key	OAuth token / service-account key
AWS ECR	https://<account>.dkr.ecr.<region>.amazonaws.com	AWS	aws ecr get-login-password
Azure Container Registry	https://<name>.azurecr.io	Registry name / service principal	ACR password / token
Quay.io	https://quay.io	Quay username	Robot-account token
Self-hosted (Harbor, registry)	https://registry.your-company.com	Registry username	Registry password / token

See Secrets for full examples of each.

List pull secrets

curl https://api.cumin.dev/secrets/pull \
  -H "Authorization: Bearer $TOKEN"

Update a pull secret

curl -X PUT https://api.cumin.dev/secrets/pull \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "<secret-id>", "server": "https://ghcr.io", "username": "new-user", "password": "new-token" }'

Delete a pull secret

curl -X DELETE https://api.cumin.dev/secrets/pull/<secret-id> \
  -H "Authorization: Bearer $TOKEN"

Using a pull secret on an app

Pass the pull secret’s id as pull_secret_id when creating an app — see the Apps API.

Next steps

• Secrets — best practices and common registry servers
• Apps API — reference pull secrets from apps
• S3 API — scoped access keys are a related credential type