Secrets

This stores a secret named API_KEY for one destination, api.example.com:

curl --unix-socket /var/lib/shard/shard.sock -X PUT -H 'Content-Type: application/json' -d '{"value":"<value>","destinations":["api.example.com"]}' http://localhost/v0/secrets/API_KEY

A create takes secrets by name, and so does the grant to a stopped sandbox. No route returns a secret’s value.

Each route answers an error with the Error body, unless its responses say otherwise.

List secrets, never their values

GET /v0/secrets · scope secret:*

Parameters

Name	In	Type	Required	Description
limit	query	integer (int64)	no	The most items on a page; absent returns the whole list. At least 1.
cursor	query	string	no	The next value of the previous page; this page starts after it.

Responses

Status	Body
200	SecretsResponse as application/json

Create or rotate a secret

PUT /v0/secrets/{name} · scope secret:*

Parameters

Name	In	Type	Required
name	path	string	yes

Request body

SecretRequest as application/json, required.

Responses

Status	Body
200	Secret as application/json

Remove a secret

DELETE /v0/secrets/{name} · scope secret:*

Parameters

Name	In	Type	Required	Description
name	path	string	yes
force	query	boolean	no	Remove the secret even when a sandbox still has a grant on it.

Responses

Status	Body
204	none

Objects

Secret

Field	Type	Required
destinations	array of string	yes
name	string	yes
placeholder	string	yes
updated_at	string (date-time)	yes

SecretRequest

Field	Type	Required	Description
destinations	array of string	no	The hosts the secret goes to. The first put of a name needs one; a rotation with none keeps the old ones.
placeholder	string	no
value	string	yes	At least 1 character.

SecretsResponse

Field	Type	Required
next	string or null	yes
secrets	array of Secret	yes
warnings	array of string	no