API keys
Every request carries a key:
Authorization: Bearer vmk_...
The key's shape is vmk_<id>_<secret>. The secret is shown once, when the key
is issued or rotated; only the <id> part is stored in records and can be shared
in a ticket.
Keeping it safe
- Put the key in an environment variable (
VEINMESH_API_KEY) or a password manager. Do not put it in code, notebooks, Git, screenshots or chat. - Use one key per person and a separate key for each agent or automation, so a leaked key can be revoked alone.
- A revoked key stops working within about a minute. Open WebSocket connections receive an error and close.
- Lifetime and rotation overlap are in Limits.
What a key may read
A key's scope and its principal's grant together decide what a request may read.
For /v2 the service currently enforces:
| Feature | Needs |
|---|---|
| Catalog, calendar, schemas | Any valid key |
Book snapshots (/v2/data) | book_snapshot kind, history, and a book depth |
K-lines (/v2/bars) | history and either the bar or book_snapshot kind |
Exports (/v2/exports) | The snapshot permissions above plus export |
Live (/v2/stream) | book_snapshot kind, live, and a book depth |
Venue and instrument scopes are part of a key but are not yet applied to /v2
requests. Data kinds, history, live, export and book depth are.
A refusal (403 forbidden) names the missing piece. Ask your administrator for
the smallest change that unblocks you.
Check your key
curl -s -H "Authorization: Bearer $VEINMESH_API_KEY" \
https://data.cyberun.cloud/v2/whoami
The answer contains your key record (without the secret), your principal and
the declared scope. enforcement says which parts are applied: data_kinds,
history, live, export and book_depth are true; venue and instrument
are false because those scopes are recorded but not applied to /v2 requests
yet. effective is a deprecated alias of declared, kept for one release.
/v2/whoami is the current identity endpoint even though the v1 data APIs are
retired.
Rotation and revocation
Rotation and revocation are administration operations; ask your administrator. A rotation issues a new key with the same scope and expiry and expires the old one after an overlap. With no overlap the old key stops working immediately.
If a key leaks, revocation is safer than rotation: rotation alone leaves the old secret valid until the overlap ends. An administrator can do both with the endpoints in Administration.