Consumer API
API keys
Organization API keys let an external system call the Consumer API on your organization's behalf, without a human dashboard session.
Creating a key
- Sign in as an Owner or Administrator - only these roles can view or manage API keys.
- Go to API Keys in the dashboard sidebar.
- Click Create API key, give it a descriptive name (e.g. "Front Desk Kiosk", "Slack Bot"), select the scopes it needs, and optionally set an expiration date.
- Click Create key. The raw key is shown exactly once, in a banner with a copy button.
Copy it immediately. Vestrane never stores the raw key - only a SHA-256 hash and a short, non-secret prefix (e.g. ves_live_abc123de) for identification in the dashboard list. If you navigate away without copying it, the key still exists and still works, but you can never view its raw value again - your only option is to revoke it and create a new one.
Format
ves_live_<43 random base64url characters>The ves_live_prefix makes a leaked key recognizable in logs, code scanners, and secret-scanning tools. There is currently no separate "test mode" key format - all keys are live.
Scopes
Grant only what an integration actually needs (least privilege):
| Scope | Grants |
|---|---|
locations:read | List and view locations |
access_points:read | List and view access points |
access_points:unlock | Issue remote-unlock commands |
events:read | List access events |
members:read | Reserved for a future members-listing endpoint |
Every scope is enforced server-side, on every route, every time - never inferred from what the dashboard UI happens to show. A key without access_points:unlock gets a 403 from the unlock endpoint even if it otherwise has full read access.
Expiration and revocation
- Expiration is optional. An expired key is rejected (
401) the moment its expiration has passed. - Revocationis immediate and irreversible. A revoked key stops authenticating on its very next request. If you suspect a key has leaked, revoke it first and create a replacement second - don't wait to investigate.
Treat a key like a password
- Never commit a key to source control, paste it into a chat/ticket that isn't access-controlled, or embed it in client-side code that ships to end users' browsers/devices.
- Prefer environment variables or a secrets manager in whatever system consumes it.
- Scope each key to the minimum it needs, and give each integration its own key rather than sharing one.
- Rotate (revoke + recreate) periodically and immediately after any suspected exposure.