Secrets
Goal: Securely manage API keys and connection credentials.
Credentials live in an encrypted secret store - never exposed in the UI or logs.
Generate an API key
From the portal:
- Open the APIs menu in the top bar
- Select API Keys
- Choose an expiration preset (15 min, 1 hour, 8 hours, 24 hours, 7 days, or 30 days)
- Optionally choose scopes for least privilege
- Click Generate JWT and copy the token immediately - it won't be shown again
Or ask Azi: "Create an API key for the mobile app with 30-day expiry." She generates it and shows you the key once.
Pick the right expiry
| Preset | Good for |
|---|---|
| 15 minutes | CLI smoke tests |
| 1 hour | Short automation |
| 8 hours | A full workday |
| 24 hours | Daily rotation |
| 7 days | Temporary integration |
| 30 days | Longer-lived service |
A token carries an identity, a workspace, scopes, and an expiry:
{
"sub": "you@yourteam.com",
"workspace": "workspace-id",
"scopes": ["read:queries", "execute:queries"],
"exp": 1737200000
}
Full token reference - minting, scopes, and the error envelope - is in Auth & Tokens.
Rotate connection credentials
- Open Connections and select the connection
- Click Update Credentials
- Enter the new credentials and Test
- Save
Rotation needs no downtime - the connection carries a primary and a secondary credential, so you switch to the secondary, then regenerate the primary.
Revoke
Revoke a key from APIs -> Keys -> Revoke - it stops working immediately. In an emergency, ask Azi: "Revoke all API keys for this workspace," and she disables them at once.
Best practices
| Practice | Why |
|---|---|
| Short expiry for dev keys | Limit exposure while building |
| Longer expiry for production | Avoid interruptions |
| Scope appropriately | Least necessary access |
| Rotate regularly | Shrink the compromise window |
| Use environment variables | Never hardcode secrets |
Every key creation, use, and revocation is recorded and attributable.
Next steps
- Test your API -> APIs
- Manage team access -> Permissions