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

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

keys

Create, roll and revoke the API keys your servers use to call Vestra. Use test keys while you build, and live keys for real users. Each key has scopes that limit what it can do, so a key that can only set things up can never act for a user.

Check your key

See your company, this key, and whether it is test or live.

TypeScript
const me = await vestra.keys.me();console.log(me.org.name, me.mode);

Create a key for CI

This one can only set things up. Its secret is shown only once.

TypeScript
const ci = await vestra.keys.create({ name: 'ci', scopes: ['setup'] });console.log(ci.secret);

Roll a key

You get a new secret, and the old one keeps working for an hour.

TypeScript
const rolled = await vestra.keys.roll(ci.id, { grace_seconds: 3600 });console.log(rolled.key.secret);

List your keys

The list shows only the last four characters of each.

TypeScript
const keys = await vestra.keys.list();console.log(keys.data.map((k) => k.last4));

Revoke a key

It stops working at once.

TypeScript
await vestra.keys.revoke(ci.id);

Check your key

See your company, this key, and whether it is test or live.

Python
me = vestra.keys.me()print(me.org.name, me.mode)

Create a key for CI

This one can only set things up. Its secret is shown only once.

Python
ci = vestra.keys.create(name="ci", scopes=["setup"])print(ci.secret)

Roll a key

You get a new secret, and the old one keeps working for an hour.

Python
rolled = vestra.keys.roll(ci.id, grace_seconds=3600)print(rolled.key.secret)

List your keys

The list shows only the last four characters of each.

Python
print([k.last4 for k in vestra.keys.list().data])

Revoke a key

It stops working at once.

Python
vestra.keys.revoke(ci.id)

List your keys

CLI
vestra keys

Create a key for CI

This one can only set things up. Its secret is shown only once.

CLI
vestra keys create --name ci --scopes setup

Roll a key

You get a new secret, and the old one keeps working for an hour.

CLI
vestra keys roll key_8sd --grace 3600

Revoke a key

It stops working at once.

CLI
vestra keys revoke key_8sd

Check your key

See your company, this key, and whether it is test or live.

HTTP
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.

HTTP
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.

HTTP
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.

HTTP
curl -X DELETE "$VESTRA_BASE_URL/v1/keys/key_3vd" \  -H "Authorization: Bearer $VESTRA_API_KEY"

Only people manage keys: no MCP tool creates, rolls or revokes one. Use the console, the CLI or HTTP.

Check your key

See your company, this key, and whether it is test or live.

HTTP
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.

HTTP
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.

HTTP
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.

HTTP
curl -X DELETE "$VESTRA_BASE_URL/v1/keys/key_3vd" \  -H "Authorization: Bearer $VESTRA_API_KEY"

Good to know

Scopes

A key's scope is all, the default, or any of these: runtime (ask, answer, events, files, sessions, connect, memory, routines), setup (deployments, tests, secrets, webhooks) and admin (keys, limits, your company's settings, and exporting or erasing a user). A key without the scope a route needs gets 403 scope_missing. Every route in these docs names the scope it needs.

Test and live

A key's prefix shows its mode: vk_test_ or vk_live_. A new key gets the same mode as the key that created it. A test key only sees test users, test deployments and test money.

Checking a key

Any key can call GET /v1/me, whatever its scopes. It returns your company, the key and its mode.

Rolling a key

A new key's secret is shown only once. When you roll a key, the old one keeps working for the grace period you choose, or for a day if you choose none.

The routes behind keys11 routes, each with every field in the API reference
GET/v1/meWho is calling: the company, the key, and whether it is test or live.Any key may call it.
GET/v1/orgThe company account: name, status, the wallet in billed dollars, day and month caps, alert thresholds, allowed return URLs, allowed embed origins, default deployment.Key scope: admin (or all)
PATCH/v1/orgChange the name, allowed return URLs, allowed embed origins, default deployment or default memory mode.Key scope: admin (or all)
GET/v1/keysList keys. Only the last four characters are ever shown again.Key scope: admin (or all)
POST/v1/keysCreate a test or live key. The full key is shown once.Key scope: admin (or all)
POST/v1/keys/{key_id}/rollReplace a key. The old one keeps working for a grace period you choose, then stops.Key scope: admin (or all)
DELETE/v1/keys/{key_id}Revoke a key immediately.Key scope: admin (or all)
GET/v1/audit-logEvery key use, settings change and approval answer, newest first.Key scope: admin (or all)
GET/v1/modelsThe models a deployment may choose from.Key scope: runtime (or all)
GET/v1/healthIs the API up. No key needed.
GET/v1/openapi.jsonThe whole contract, machine-readable.