Tokens & API keys¶
Three kinds of credentials: user login tokens, agent tokens and collector API keys.
Login tokens (users)¶
After login (and 2FA) the user receives signed JWTs. Two paths:
| Browser (web UI) | API / mobile app (bearer) | |
|---|---|---|
| Signature | HS256 with SECRET_KEY from the .env |
HS256 with SECRET_KEY |
| Access token | 30 minutes, in the vesana_access cookie |
12 hours, header Authorization: Bearer … |
| Renewal | silently via the vesana_refresh cookie (rotated on every renewal) |
via /api/v1/auth/refresh, capped by the session's maximum lifetime |
| Storage | HttpOnly cookies (Secure, SameSite=Strict) — JavaScript cannot read the tokens |
with the caller |
| Content | user ID, e-mail, role, tenant, permissions (not for super admins — the server derives those), permission version | as browser |
The session itself lives on the server. How long it lasts (default: 30 days without use, at most 90 days) is set under Admin → Login & Security → 2FA & Sessions — see Login sessions.
Revocation¶
Logging out, “Sign out everywhere else”, a password change, deactivating an account and permission changes take effect within seconds: on every request the server checks whether the session has been revoked and whether the permission version in the token is still current. Detected reuse of an already rotated refresh token (a sign of theft) ends the session.
SECRET_KEY protects every login
Anyone who knows the SECRET_KEY can mint valid login tokens for any account. It lives in the .env (mode 600, see Hardening checklist). A new SECRET_KEY signs out all users.
Agent token¶
For agents on monitored machines.
| Field | Value |
|---|---|
| Format | vesana_agent_ + 43 characters (32 random bytes, URL-safe base64) |
| Server storage | SHA-256 hash only |
| Agent storage | plaintext in the agent config: Linux /etc/vesana-agent/config.yaml (mode 600), Windows C:\ProgramData\Vesana\Agent\config.yaml (Administrators and SYSTEM only) |
| Lifetime | unlimited, until revoked |
| Binding | to exactly one host; a new token invalidates the previous one |
| Auth header | X-Agent-Token: vesana_agent_… |
Creating¶
In the UI via Setup agent on the host (permission agents.manage). The plaintext is shown exactly once; only the hash is stored.
Renewing and revoking¶
Host detail → Manage host → Renew token issues a new token; the old one is invalid immediately, and the agent must be reinstalled with the new token (or you put it into the config by hand and restart the service). Revoke token (or Remove agent on the agent chip) locks the agent out without issuing a new token.
The receiver remembers valid logins for up to 60 seconds; a revocation still takes effect within one second.
Collector API key¶
For collectors in the customer network.
| Field | Value |
|---|---|
| Format | vesana_ + 43 characters (32 random bytes, URL-safe base64) |
| Server storage | SHA-256 hash only |
| Collector storage | plaintext in /etc/vesana/collector.env |
| Auth header | X-API-Key: vesana_… |
| Binding | to exactly one collector |
The key is created together with the collector and shown once (inside the install command). Regenerate Key on the collector (permission collectors.edit plus identity confirmation) deactivates the old key immediately; the collector must then be reinstalled with the new key. Authentication checks only the hash of the full key — the leading characters shown in lists are just there to tell keys apart.
There are no personal API keys for users. Scripts and integrations log in like the UI does and use the bearer token (see API → Authentication).
Hashing¶
Agent tokens and API keys are stored only as SHA-256 hashes. A database leak therefore reveals no working token. No salt is needed because the tokens themselves carry 32 random bytes.
HTTPS only¶
Vesana creates a self-signed certificate on first start, so HTTPS is always available. The HTTP port redirects every request to HTTPS (301) — only the path for the Let's Encrypt validation stays on HTTP. For production: a certificate from Vesana (Let's Encrypt) or your own, see TLS / certificate.
Audit¶
Token operations appear in the audit log, among them agent_token_create, agent_token_revoke, collector_create and collector_regenerate_key.