Keys, tokens and credentials
Every credential a Sovaria project uses — anon key, service role key, custom keys, access and refresh tokens, CLI tokens, the database password and secrets — where each may be used, how long it lasts and what to do if one leaks.
Each credential has one job. Use the weakest one that does it, and keep anything secret on servers.
| Credential | Secret? | Use it in | Never in | Lasts |
|---|---|---|---|---|
| Anon key (publishable) | No | Browsers, mobile apps, any client | — | Until rotated |
| Service role key | Yes | Your servers, CI, functions | Browsers, apps, repositories, logs | Until rotated |
| Custom API key | Yes | One integration or job, with a role (admin, editor, viewer) and an optional expiry | Clients | Until it expires or is revoked |
| Access token (app user) | Yes, short-lived | Sent by your app for the signed-in user | Logs, URLs | 15 minutes by default (at most 60) |
| Refresh token (app user) | Yes | Stored by the SDK to get new access tokens | Anywhere shared | 7 days by default; replaced on every refresh |
| Team session / CLI token | Yes | The console; sov login stores it in your OS keyring | Shared machines, CI (use a key instead) | Until you sign out |
| Database password | Yes | Direct Postgres connections from servers and tools | Clients | Until you reset it |
| Project secrets | Yes | Read by your functions at run time | — | Until changed |
Anon key
Identifies your project to Sovaria; it grants nothing by itself. A visitor with it can do only what your rules allow anonymous callers, which is nothing until you allow it (How access is decided). It is safe in client code — like Supabase's anon key or Firebase's API key.
Service role and custom keys
- Shown in full once, when created — copy it straight into your secret store. Sovaria keeps only a keyed hash; nobody can read it back.
- Rotate creates a replacement and revokes the old key: deploy the new value first, then rotate.
- Owners and admins are emailed whenever a key is created or revoked.
- Prefer a custom key per integration (with an expiry) over sharing the service role key: you can revoke one without breaking the others.
sov keys list
sov keys create --name ci-deploy --role admin # printed once
sov keys revoke <key-id>App users' tokens
Signing in returns an access token and a refresh token. The SDKs send the access token with every request and swap the refresh token for a new pair before it expires; each refresh token works once (rotation), so a stolen one that is used twice ends the session. Set the lifetimes in Authentication › Sessions (Authentication settings reference). Signing out, Sign out other devices, removing the user or changing their password ends sessions.
Access tokens are signed with the project's key (ES256). To check one on your own server, fetch the public keys from https://<project-ref>.sovarias.in/auth/v1/.well-known/jwks.json.
CLI and CI credentials
sov login stores your session in the operating system's keyring (macOS Keychain, Windows Credential Manager, libsecret) or, where there is none, in ~/.sovaria/credentials.toml readable only by you. In CI, set SOVARIA_API_KEY (a custom key) or SOVARIA_ACCESS_TOKEN instead — they take precedence over stored logins. See Environment variables.
Database password
Only for direct Postgres connections from servers and tools (Database: connection, compute, disk and backups). A direct connection is not filtered by your access policies — treat the password like the service role key. Reset it under Project Settings › Database.
Function secrets
Store API keys for other services (Stripe, OpenAI…) as project secrets and bind them to functions; they are encrypted at rest, never shown again after saving and never sent to clients (Functions).
If a credential leaks
| Leaked | Do this now |
|---|---|
| Service role or custom key | Create a replacement, deploy it, revoke the old key (Rotate). Check the audit log and request logs for use from unknown IPs. |
| A user's tokens | End the user's sessions from the Users page (or have them change their password, which ends them too). |
| Your own CLI or console session | Account › Security › Your devices: sign out the others, then sign in again. |
| Database password | Reset it under Project Settings › Database and update your servers. |
| A function secret | Rotate it at the provider, then update the secret. |
| Anon key | Nothing urgent — it is public by design. Rotate it if you want to cut off an old app version. |