Secret keys

Create API keys that let scripts and the SDKs act on a team with a chosen role, and see how each key is used.

A secret key lets a program call the VOLT API without signing in as you: a script, a pipeline on another machine, or the TypeScript and Python SDKs. Each key belongs to one team and takes one of the team's roles, which limits what it can do.

Secret keys are under Settings › Secret Keys (/dashboard/settings/secret-keys). Every action on them needs a team-secret-key permission. Among the built-in roles, only Owner has them.

To	Permission
See the keys, the metrics and a key's usage	`team-secret-key:read`
Create a key	`team-secret-key:create`
Revoke a key	`team-secret-key:create` on the server (the menu item also checks `team-secret-key:update`)
Delete a key	`team-secret-key:delete`

Create a key

Click Create new, or press N on the page.

In Create Secret Key, enter a Key Name (for example, Production API Key) and pick the Role the key acts with. Click Create Key.

Secret Key Created shows the key once. Copy it and store it somewhere safe: VOLT keeps only a hash of it and cannot show it again. Tick I copied or stored this secret key somewhere safe. to enable Done.

A key looks like vsk_ followed by 64 hexadecimal characters. Its first 14 characters, the prefix, are stored in clear so you can recognize the key in lists and logs.

What a key can do

A request that sends a key in its Authorization: Bearer header is authenticated as that key:

It acts in the key's team only. A request for another team is refused.
It has the permissions of the key's role, so a key with a Viewer role can only read. Changing the role's permissions on Manage Roles changes what the key can do. Deleting the role deletes the key.
It acts as the member who created it, for anything recorded under a user.
Revoked and deleted keys are refused with a 401.

GET /api/teams/secret-keys/me returns the key that made the request, including its team.

The Secret Keys page

The list shows each key's Name, Prefix, Role, Status (active or revoked), Created By and Last Used (Never for an unused key). Click a key to open its usage page. Each row's menu has:

Action	What it does
View Usage	Opens the key's usage page.
Copy Prefix	Copies the key's prefix.
Revoke Key	Turns the key off after confirmation. Applications using it lose access immediately. The key stays in the list as revoked, with its history, and cannot be turned back on. Revoked keys don't offer this item.
Delete	Deletes the key permanently after confirmation.

Notebooks get keys of their own, so their kernels can use the Python SDK: these appear in the list as notebook:<notebook id>, with the role of the member who first opened the notebook. VOLT deletes such a key when it deletes the notebook. If you revoke or delete one yourself, that notebook's SDK calls are refused. See Notebooks.

Metrics

Metrics opens Secret Key Metrics (/dashboard/settings/secret-keys/metrics): the requests made with all of the team's keys over the last 30 days.

Section	Shows
Total Requests, Avg Response Time, Active Keys	Totals for the period.
Unique Endpoints	The number of endpoints in Top Endpoints.
Requests Over Time	Requests per day, with the Total and the Success Rate.
Top Endpoints	The ten most requested endpoints.
Per-Key Breakdown	For each key: Key, Role, Requests, Avg Response, Last Used and Status.

A key's usage

A key's page (/dashboard/settings/secret-keys/:secretKeyId) covers that key over the last 30 days.

Section	Shows
Total Requests, Avg Response Time, Success Rate, Last Used	Totals for the key.
Hourly Requests	Requests per hour of the day (UTC) over the last 24 hours, with the 24h count and the Peak Hour.
Top Endpoints	The endpoints the key calls most.
Status Codes	The share of each HTTP status code.
Recent Requests	The latest requests, with Method, Path, Status, Time (response time) and When.

VOLT records every request made with a key: method, route, status code, response time, IP address and user agent. The success rate counts 2xx responses.

Use a key from code

Send the key as a bearer token. The SDKs do it for you.

curl -H "Authorization: Bearer $VOLT_SECRET_KEY" \
  https://volt.example.edu/api/teams/secret-keys/me

from voltsdk import VoltClient

# Reads VOLT_SECRET_KEY and VOLT_BASE_URL when you pass nothing.
client = VoltClient(secret_key="vsk_...", base_url="https://volt.example.edu")

import { createVoltClient, secretKey } from '@voltstack/voltclient';

const client = createVoltClient('https://volt.example.edu/api', {
    credential: secretKey('vsk_...')
});

See @voltstack/voltclient and Python SDK for what the clients can do, and REST & realtime API for the endpoints.