Secrets

Endpoints for storing squad secrets, configuring external secret providers, rotating values, and auditing secret access. Secret values are never returned by the API once stored.

Prerequisites

• API key: Authorization: Bearer <token>
• An Operator key — all secret endpoints require Operator scope

Endpoints

Method	Path	Description
GET	/api/squads/{squadId}/secrets	List secrets for a squad (metadata only)
POST	/api/squads/{squadId}/secrets	Create a secret
PATCH	/api/secrets/{id}	Update secret metadata
POST	/api/secrets/{id}/rotate	Rotate a secret to a new version
DELETE	/api/secrets/{id}	Delete (revoke) a secret
GET	/api/secrets/{id}/usage	Where the secret is bound and used
GET	/api/secrets/{id}/access-events	Access audit trail for the secret
GET	/api/squads/{squadId}/secret-providers	List supported provider types
GET	/api/squads/{squadId}/secret-providers/health	Health of configured providers
GET	/api/squads/{squadId}/secret-provider-configs	List provider configurations
POST	/api/squads/{squadId}/secret-provider-configs	Create a provider configuration
GET	/api/secret-provider-configs/{id}	Read a provider configuration
PATCH	/api/secret-provider-configs/{id}	Update a provider configuration
DELETE	/api/secret-provider-configs/{id}	Delete a provider configuration
POST	/api/secret-provider-configs/{id}/default	Mark a configuration as the squad default
POST	/api/secret-provider-configs/{id}/health	Run a health check against a provider
POST	/api/squads/{squadId}/secret-provider-configs/discovery/preview	Preview a provider connection before saving a config
POST	/api/squads/{squadId}/secrets/remote-import/preview	List importable secrets from a configured provider
POST	/api/squads/{squadId}/secrets/remote-import	Import selected secrets from a provider

Supported providers: local_encrypted, aws_secrets_manager, gcp_secret_manager, vault.

---

List secrets

GET /api/squads/{squadId}/secrets

Returns secret metadata for the squad. Values are never included.

Response fields

Field	Type	Description
id	UUID	Secret ID
key	string	Reference key (e.g. STRIPE_API_KEY)
name	string	Human-readable name
provider	string	Backing provider
status	string	active, disabled, archived, or deleted
managedMode	string	slaw_managed (value held by SLAW) or external_reference (resolved from the provider)
externalRef	string | null	Provider-side reference, for external_reference secrets
latestVersion	integer	Current version number
description	string | null	Optional description
lastResolvedAt	timestamp | null	Last time the value was resolved for use
lastRotatedAt	timestamp | null	Last rotation time
createdAt	timestamp	Creation time

---

Create a secret

POST /api/squads/{squadId}/secrets

Request body

Field	Type	Required	Description
name	string	yes	Human-readable name
key	string	no	Reference key ([A-Za-z0-9_.-]+); derived from name if omitted
provider	string	no	One of the supported providers
providerConfigId	UUID	no	Provider configuration to use
managedMode	string	no	slaw_managed (default) or external_reference
value	string	conditional	Required for slaw_managed secrets; the raw secret value
externalRef	string	conditional	Required for external_reference secrets; forbidden otherwise
description	string	no	Optional description
providerVersionRef	string	no	Provider-side version pointer
providerMetadata	object	no	Provider-specific metadata

A slaw_managed secret must supply value; an external_reference secret must supply externalRef and must not supply value. Returns 201 Created.

Example

curl -X POST http://localhost:3100/api/squads/$SQUAD_ID/secrets \
  -H "Authorization: Bearer $SLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Stripe API Key", "key": "STRIPE_API_KEY", "value": "sk_live_..." }'

---

Update a secret

PATCH /api/secrets/{id}

Updates metadata only — name, key, status, providerConfigId, description, externalRef, or providerMetadata. Use rotate to change the value.

---

Rotate a secret

POST /api/secrets/{id}/rotate

Creates a new version. Provide value for managed secrets, or externalRef / providerVersionRef for externally referenced secrets.

Request body

Field	Type	Required	Description
value	string	conditional	New raw value (managed secrets)
externalRef	string	conditional	New provider reference (external secrets)
providerVersionRef	string	no	New provider version pointer
providerConfigId	UUID	no	Switch the backing provider configuration

---

Delete a secret

DELETE /api/secrets/{id}

Revokes the secret. Bindings that depend on it will fail to resolve.

---

Secret usage

GET /api/secrets/{id}/usage

Returns the bindings and consumers that reference the secret, so you can confirm impact before rotating or deleting.

---

Access events

GET /api/secrets/{id}/access-events

Returns the access audit trail for the secret.

Response fields

Field	Type	Description
provider	string	Provider that served the value
actorType / actorId	string	Who triggered the access
consumerType / consumerId	string	What consumed the value (agent, plugin, binding)
configPath	string | null	Config key the value was injected into
issueId	UUID | null	Issue context, when applicable
heartbeatRunId	UUID | null	Heartbeat run context, when applicable
outcome	string	Resolution outcome
errorCode	string | null	Failure code, when the access failed
createdAt	timestamp	When the access occurred

---

Provider configurations

Provider configs hold the non-sensitive connection settings for an external secret store. Credentials themselves are never persisted in a provider config — the API rejects sensitive keys (access keys, tokens, passwords, private keys) in the config body.

• GET /api/squads/{squadId}/secret-providers — list supported provider types
• GET /api/squads/{squadId}/secret-providers/health — aggregate provider health
• POST /api/squads/{squadId}/secret-provider-configs — create a configuration
• GET / PATCH / DELETE /api/secret-provider-configs/{id} — manage one configuration
• POST /api/secret-provider-configs/{id}/default — set the squad default
• POST /api/secret-provider-configs/{id}/health — test connectivity

---

Discovery & remote import

For external providers, these endpoints let you validate a connection and pull existing secrets in without retyping their values. All three require an Operator key.

Preview a provider connection

POST /api/squads/{squadId}/secret-provider-configs/discovery/preview

Tests a provider connection before you persist a configuration.

Field	Type	Required	Description
provider	string	yes	One of the supported providers
config	object	no	Non-sensitive connection settings to test (default {})

Preview a remote import

POST /api/squads/{squadId}/secrets/remote-import/preview

Lists the secrets available in a configured provider so you can choose what to import. Each candidate is classified (e.g. ready, duplicate, conflict).

Field	Type	Required	Description
providerConfigId	UUID	yes	Provider configuration to read from
query	string	no	Filter candidates by name
pageSize	integer	no	Page size, 1–100
nextToken	string	no	Pagination cursor from a previous page

Import selected secrets

POST /api/squads/{squadId}/secrets/remote-import

Imports the chosen secrets as external_reference entries. Returns counts of imported, skipped, and errored secrets.

Field	Type	Required	Description
providerConfigId	UUID	yes	Provider configuration to import from
secrets	array	yes	1–100 selections, each with externalRef (required) plus optional name, key, description, providerVersionRef, providerMetadata

---

Next steps

• Routines — bind secrets into routine environments
• Activity — secret writes appear in the squad audit trail