Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

Account

Your company's account: who is calling, its keys, its caps, what it spent and the models it may use.

Send Authorization: Bearer vk_test_... on every call. Every route of Account.

POST/v1/keys/{key_id}/rollReplace a key.

The old one keeps working for a grace period you choose, then stops.

Your API key, scope admin or all. On the card: keys. Every call here is a checked sample.

Request2 fields

Path

key_idstringrequiredThe API key's id (key_...).
Type
string

Body, if you send one

grace_secondsintegerHow long the old key keeps working, in seconds, up to 7 days. Default 86400 (a day); 0 stops it at once.
Default
86400
Limits
0 to 604800.
Answers 2013 fields
object"api_key_roll"Always api_key_roll.
Type
"api_key_roll"
keyobjectThe new key, with its secret, shown once.
idstringThe key's id.
Example
key_8f2k
object"api_key"Always api_key.
Type
"api_key"
mode"live" | "test"live or test: what the key reaches. A test key sees only test users, test deployments and test money.
Type
"live" | "test"
namestring | nullThe name you gave it; null when it has none.
Type
string | null
prefixstringThe start of the secret, to tell keys apart: vk_live_ or vk_test_ and a few characters.
Example
vk_test_8f2k
last4stringThe last four characters of the secret.
Type
string
scopes("all" | "runtime" | "setup" | "admin")[]What the key may call: all, or any of runtime (conversations, work, routines, connected apps, files, memory, usage), setup (deployments, tests, secrets) and admin (users and keys).
Type
("all" | "runtime" | "setup" | "admin")[]
status"active" | "expiring" | "expired" | "revoked"active: works, with no end. expiring: works until expires_at (a rolled key in its grace period, or one made to expire). expired or revoked: refused.
Type
"active" | "expiring" | "expired" | "revoked"
created_atstringWhen it was made, as an ISO 8601 date and time in UTC.
Type
string
last_used_atstring | nullWhen it last made a call; null when it never has.
Type
string | null
expires_atstring | nullWhen it stops working; null when it never does.
Type
string | null
revoked_atstring | nullWhen it was revoked; null while it is not.
Type
string | null
secretstringThe whole key. It is shown this once: store it now, as Vestra keeps only its hash.
Example
vk_test_...
previousobjectThe old key: it works until its expires_at, then stops.
idstringThe key's id.
Example
key_8f2k
object"api_key"Always api_key.
Type
"api_key"
mode"live" | "test"live or test: what the key reaches. A test key sees only test users, test deployments and test money.
Type
"live" | "test"
namestring | nullThe name you gave it; null when it has none.
Type
string | null
prefixstringThe start of the secret, to tell keys apart: vk_live_ or vk_test_ and a few characters.
Example
vk_test_8f2k
last4stringThe last four characters of the secret.
Type
string
scopes("all" | "runtime" | "setup" | "admin")[]What the key may call: all, or any of runtime (conversations, work, routines, connected apps, files, memory, usage), setup (deployments, tests, secrets) and admin (users and keys).
Type
("all" | "runtime" | "setup" | "admin")[]
status"active" | "expiring" | "expired" | "revoked"active: works, with no end. expiring: works until expires_at (a rolled key in its grace period, or one made to expire). expired or revoked: refused.
Type
"active" | "expiring" | "expired" | "revoked"
created_atstringWhen it was made, as an ISO 8601 date and time in UTC.
Type
string
last_used_atstring | nullWhen it last made a call; null when it never has.
Type
string | null
expires_atstring | nullWhen it stops working; null when it never does.
Type
string | null
revoked_atstring | nullWhen it was revoked; null while it is not.
Type
string | null
TypeScript
const rolled = await vestra.keys.roll('key_8sd');
Python
rolled = vestra.keys.roll("key_8sd")
CLI
vestra keys roll key_8sd
HTTP
# Check your key. See your company, this key, and whether it is test or live.curl "$VESTRA_BASE_URL/v1/me" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Create a key for CI. This one can only set things up. Its secret is shown only once.curl "$VESTRA_BASE_URL/v1/keys" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "ci", "scopes": ["setup"] }' # Roll a key. You get a new secret, and the old one keeps working for an hour.curl "$VESTRA_BASE_URL/v1/keys/key_3vd/roll" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "grace_seconds": 3600 }' # Revoke a key. It stops working at once.curl -X DELETE "$VESTRA_BASE_URL/v1/keys/key_3vd" \  -H "Authorization: Bearer $VESTRA_API_KEY"
HTTP

No sample in your language for this route, so here it is over HTTP.

# Check your key. See your company, this key, and whether it is test or live.curl "$VESTRA_BASE_URL/v1/me" \  -H "Authorization: Bearer $VESTRA_API_KEY" # Create a key for CI. This one can only set things up. Its secret is shown only once.curl "$VESTRA_BASE_URL/v1/keys" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "ci", "scopes": ["setup"] }' # Roll a key. You get a new secret, and the old one keeps working for an hour.curl "$VESTRA_BASE_URL/v1/keys/key_3vd/roll" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "grace_seconds": 3600 }' # Revoke a key. It stops working at once.curl -X DELETE "$VESTRA_BASE_URL/v1/keys/key_3vd" \  -H "Authorization: Bearer $VESTRA_API_KEY"