The secrets API is deliberately minimal. Secret values are never returned in any response, ever. The API lets you create, list metadata for, rotate, and delete secrets, and it lets integrations attach secrets by reference. Decryption happens only inside the orchestrator process at the moment of use. If you find yourself wanting an endpoint that reveals a secret value, you are doing the wrong thing. Fetch the value in the process that needs it, through the usual integration flow, not through this API.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/secretsList secret metadata
POST/v1/companies/{cid}/secretsCreate or update a secret
GET/v1/companies/{cid}/secrets/{name}Get one secret’s metadata
POST/v1/companies/{cid}/secrets/{name}/rotateRotate a secret
DELETE/v1/companies/{cid}/secrets/{name}Delete a secret

​
The secret metadata object

{
  "name": "anthropic_api_key",
  "companyId": "cmp_a1b2c3",
  "category": "api_key",
  "integrationId": "int_d4e5f6",
  "description": "Anthropic API key for Claude agents",
  "createdAt": "2026-03-01T09:00:00Z",
  "updatedAt": "2026-04-05T14:22:00Z",
  "lastUsedAt": "2026-04-11T10:38:12Z",
  "rotatedAt": "2026-04-05T14:22:00Z"
}
Note: no value field. Ever.

​
Listing secrets

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/secrets \
  -H "Authorization: Bearer $CA_API_TOKEN"
Returns metadata for every secret in the company. Optional filters:
  • category — api_key, oauth_token, mtls_cert, webhook_secret
  • integrationId — attached to a specific integration

​
Creating a secret

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/secrets \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "anthropic_api_key",
    "value": "sk-ant-...",
    "category": "api_key",
    "description": "Anthropic API key for Claude agents"
  }'
Important:
  • The value is write-only. It goes in, encrypted with the master key, and never comes back out.
  • If a secret with the same name already exists, this endpoint overwrites it and returns the new metadata with an updated rotatedAt.
  • The response does not include the value. It includes only the metadata.
The API transport must be TLS. The orchestrator refuses POST /v1/secrets over plain HTTP unless the host is localhost.

​
Rotating a secret

Rotation is the same as create-with-the-same-name, but with a cleaner verb and a 24-hour grace window for the old value: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/secrets/anthropic_api_key/rotate \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "value": "sk-ant-new-..." }'
During the grace window:
  • New runs use the new value
  • Runs that started before the rotation continue to use the old value until they finish
  • The old value is deleted at the end of the window
You can configure the grace window per-integration if needed (some integrations cannot tolerate two valid tokens at once).

​
Deleting a secret

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/secrets/anthropic_api_key \
  -X DELETE \
  -H "Authorization: Bearer $CA_API_TOKEN"
Delete is destructive: the value is wiped and cannot be recovered. Any integration depending on the secret breaks immediately. If the secret is referenced by an active integration, the delete is refused with secret_in_use. Remove the integration first.

​
Integration slots

Templates and Clipmart companies use “slots”: placeholders where a secret is expected but not yet provided. When you install a template, the import flow prompts you to fill in each slot by posting to /v1/secrets with the slot name. The orchestrator tracks which slots are empty and blocks the company from running workflows until all required slots are filled. List empty slots: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/secrets?status=empty_slot \
  -H "Authorization: Bearer $CA_API_TOKEN"

​
Master key

The master key itself is not accessible through this API at all. It is managed at the filesystem or secret-manager layer via the MASTER_KEY_SOURCE env var. See deploy/secrets for rotation procedures.

​
Auth and scopes

Secret endpoints require the admin scope or a company-scoped write token (company:<id>:write). Plain write is not enough, because secret values are sensitive and the broader write scope allows touching everything else in the instance.

​
Webhooks

EventWhen
secret.createdNew secret or overwritten
secret.rotatedExplicit rotation
secret.deletedSecret deleted
secret.usedAggregated weekly; not per-use

​
Next

  • Deploy/Secrets — the master key and the secret store at the infrastructure layer
  • Companies — the scope that owns every secret
  • Authentication — the scopes required for secret operations