Authentication
How API keys work, how they are stored, and how to rotate them.
Key format
Every UpVoot API key follows this format:
sk_live_<64 hex characters>
Example:
sk_live_a3f9c2d1e84b7f5a6c2d9e1f3b8a4d7c2e9f1a3b5c8d2e4f6a8b1c3d5e7f9a2
| Part | Length | Purpose |
|---|---|---|
sk_live_ | 8 chars | Type prefix — identifies this as a live key |
| random hex | 64 chars | 256 bits of cryptographic entropy |
Security model
- The raw key is never stored anywhere — not in the database, not in logs.
- Only a SHA-256 hash and an 8-character display suffix are persisted.
- Validation is constant-time:
SHA256(incoming) === stored_hash. - A compromised database reveals only hashes and suffixes. Neither can reconstruct the raw key.
- Each key is scoped to one agent. A key for Agent A cannot access Agent B's configuration or billing.
Key lifecycle
- Created — You click "New key" in the dashboard. A random key is generated.
- Displayed once — The full raw key is shown in a modal. Copy it now.
- Active — The key authenticates WebSocket connections and loads the agent config.
- Revoked — You click "Revoke". The key is immediately marked inactive; ongoing calls are not interrupted, but new connections are rejected.
Using a key in a WebSocket connection
Pass the raw key as the last path segment of the WebSocket URL. No headers or query parameters are needed.
# Format wss://api.upvoot.com/voice/<raw-key> # Example wss://api.upvoot.com/voice/sk_live_a3f9c2d1e84b7f5a…
The platform validates the key before accepting the WebSocket upgrade. If the key is invalid or revoked, the server returns HTTP 401 and closes the connection.
Error responses
| HTTP status | Meaning |
|---|---|
401 Unauthorized | Key not found or invalid format |
403 Forbidden | Key is revoked (is_active = false) |
402 Payment Required | Insufficient point balance on the account |
Key rotation
There is no automatic rotation. To rotate a key:
- Generate a new key for the same agent.
- Update your telephony provider configuration to use the new key.
- Revoke the old key.
We recommend rotating keys every 90 days or immediately after any suspected leak.