API reference

Secrets

Encrypted environment variables of an app: set, list names, remove, and choose which ones a build may see.

Secrets are environment variables stored encrypted. The API lists their names and never their values. A secret reaches the app’s machines at their next start; with "staged": false Rytiv rolls the app right away. Each secret carries a build choice: whether the next source build sees it as environment, or only the running machines do.

Secrets that Rytiv manages for you (the DATABASE_URL of an attached database, the S3_* keys of an attached bucket) cannot be changed or removed here; detach the resource instead.

Endpoints

GET /v1/apps/:name/secrets: The app’s secrets: names, when they changed, whether Rytiv manages them, and whether a build sees them. Never a value
PUT /v1/apps/:name/secrets: Sets secrets. staged: true (the default) applies them at the next deploy; staged: false rolls the app now. build chooses per key whether the next build sees it
DELETE /v1/apps/:name/secrets/:key: Removes one secret

GET /v1/apps/:name/secrets

The app’s secrets: names, when they changed, whether Rytiv manages them, and whether a build sees them. Never a value.

Auth: API key with full access or the scope deploy or deploy:<app> for this app, or the scope read. Every class of agent token may call it.

Path parameters

Name	Description
`name`	The app’s name.

Example request

curl -X GET "https://api.rytiv.app/v1/apps/<name>/secrets" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

200 with a list of secrets, each:

[
  {
    "name": "my-app",
    "updatedAt": "2026-10-21T09:00:00Z",
    "managed": true
  }
]

Field	Type	Present	Description
`name`	string	always	The secret’s name.
`updatedAt`	string (ISO 8601)	always	When it last changed.
`managed`	boolean	always	Whether Rytiv manages it (an attachment or a database password); then it cannot be changed here.
`managedReason`	`attachment` \| `resource-password`	if set	`attachment` or `resource-password`.
`build`	boolean	if set	Whether the next source build sees it.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

PUT /v1/apps/:name/secrets

Sets secrets. staged: true (the default) applies them at the next deploy; staged: false rolls the app now. build chooses per key whether the next build sees it.

Auth: API key with full access or the scope deploy or deploy:<app> for this app. An agent token of class sandbox or twin may call it; class production is refused (agent-token-production-readonly).

Path parameters

Name	Description
`name`	The app’s name.

Request body

JSON, the shape SetSecretsRequest of the contract.

Field	Type	Required	Description
`secrets`	object of string	optional	Names and values to set. Names like `MY_SECRET`; the platform’s own `RYTIV_` names are refused.
`staged`	boolean	optional	`true` (default): the values apply at the next deploy. `false`: Rytiv rolls the app now if a machine lacks a new value. default `true`.
`build`	object of boolean	optional	Per secret name, whether the next source build sees it as environment.

Example request

curl -X PUT "https://api.rytiv.app/v1/apps/<name>/secrets" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"secrets":{"<key>":"<value>"}}'

Response

200 with a JSON body.

Errors

Status	Code	Meaning
400	`bad-request`	The request is malformed or a field is out of range. `error` names every field; `issues` lists them.
401	`unauthenticated`	No API key, or one that does not work.
403	`org-limit-computers`	The organization has as many computers as it may have. The body carries `limit` and `current`. Delete one, or contact us for more.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.

DELETE /v1/apps/:name/secrets/:key

Removes one secret.

Path parameters

Name	Description
`name`	The app’s name.
`key`	The secret’s name.

Example request

curl -X DELETE "https://api.rytiv.app/v1/apps/<name>/secrets/<key>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"

Response

204 with no body.

Errors

Status	Code	Meaning
401	`unauthenticated`	No API key, or one that does not work.
403	`token-scope`	The key’s scopes do not cover this route.
404	`not-found`	Not found, or not yours. An object of another organization answers like one that does not exist.