Concepts
Authentication

Authentication

Onvera supports two authentication methods depending on your use case.

Authentication Methods

JWT - Web UI

Used by: Web dashboard

How it works:

  1. User authenticates via the web interface
  2. System issues a JWT token
  3. Frontend includes token in Authorization: Bearer <token> header
  4. Backend verifies token and extracts user information

Characteristics:

  • Short-lived tokens (typically 1 hour)
  • Automatic token refresh
  • Browser-based authentication flow
  • Not suitable for CLI or programmatic access

API Keys - CLI & Programmatic

Used by: CLI, API integrations, CI/CD

How it works:

  1. User creates API key in dashboard
  2. API key is stored securely (hashed in database)
  3. Client includes key in X-API-Key: <key> header
  4. Backend validates key and returns API key context

API Key Format:

onv_sk_live_<random_token>

Characteristics:

  • Long-lived (until revoked or expired)
  • Suitable for automation
  • Can be scoped to specific permissions
  • Can be revoked at any time

API Key Scopes

API keys can have scopes that limit what they can do:

  • deployments:read - Read deployments
  • deployments:write - Create/update deployments
  • deployments:delete - Delete deployments
  • operations:read - Read operations
  • org:read - Read organization information

Default: API keys have all scopes unless restricted.

Creating API Keys

Create API keys in the Onvera dashboard (opens in a new tab):

  1. Navigate to Organization > API Keys
  2. Click "Create API Key"
  3. Copy the key immediately (it's only shown once)
  4. Store securely

API Key Expiration

API keys can have expiration dates:

  • No expiration - Key is valid until revoked
  • Expiration date - Key expires on specified date

Expired keys cannot be used and must be replaced.

Revoking API Keys

Revoke API keys in the dashboard:

  1. Navigate to Organization > API Keys
  2. Find the key you want to revoke
  3. Click "Revoke"

Revoked keys cannot be used and cannot be restored.

Using API Keys

CLI

# Browser login (recommended)
onvera auth login
 
# Direct API key
onvera auth login --token onv_sk_live_...
 
# Environment variable
export ONVERA_API_KEY=onv_sk_live_...
onvera ls

API

# Include API key in header
curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/deployments

Security Best Practices

  1. Never commit API keys to version control
  2. Use environment variables for API keys in CI/CD
  3. Rotate keys regularly (every 90 days recommended)
  4. Revoke unused keys immediately
  5. Use scoped keys when possible (limit permissions)
  6. Monitor key usage via audit logs

Audit Visibility

All API key usage is logged:

  • When the key was used
  • Which endpoint was accessed
  • Which organization/user context was used

View audit logs in the dashboard under Organization > Audit Logs.

Related Concepts

OperationsOverview