Set a vault key

PUT

/vault/{name}

curl --request PUT \
  --url http://127.0.0.1:7700/api/vault/FACTORY_API_KEY \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "value": "example-key-value" }'

• On the box itself (the default listen address)
• From another device, with a paired device token, when BOX_LISTEN allows it

Owner only. Sets or replaces one key in /etc/box/vault.env, which stays readable by root only. The value is one line of up to 8192 characters. The log records that the name was set, never the value. No route reads a value back. The box uses the new value straight away.

Authorizations

• deviceToken
• accessToken

Parameters

Path Parameters

name

required

string

/^[A-Z][A-Z0-9_]{1,63}$/

Capital letters, digits and _, 2 to 64 characters, starting with a letter.

Example

FACTORY_API_KEY

Request Body^required

Media typeapplication/json

object

value

required

The key. Never shown again.

string

Example

{
  "value": "example-key-value"
}

Responses

200

The name and when it was set.

Media typeapplication/json

object

name

required

string

setAt

required

string format: date-time

Example ^generated

{
  "name": "example",
  "setAt": "2026-04-15T12:00:00Z"
}

400

A bad name or value. The message never repeats the value.

Media typeapplication/json

object

error

required

What went wrong

string

Example ^generated

{
  "error": "example"
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "only the box's own screen or the owner's paired device can do this"
}