API
Authentication

API Authentication

The Onvera API uses API key authentication for all requests.

API Key Format

API keys have the following format:

onv_sk_live_<random_token>

Example:

onv_sk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

Authentication Header

Include your API key in the X-API-Key header:

curl -H "X-API-Key: onv_sk_live_..." \
  https://api.onvera.io/api/v1/deployments

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 keys are only displayed once when created. Store them securely.

API Key Scopes

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

Available Scopes

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

Default Scopes

By default, API keys have all scopes unless restricted. You can restrict scopes when creating a key in the dashboard.

Scope Requirements

Each endpoint requires specific scopes:

  • GET /v1/deployments - Requires deployments:read
  • POST /v1/deployments - Requires deployments:write
  • GET /v1/deployments/{id} - Requires deployments:read
  • DELETE /v1/deployments/{id} - Requires deployments:write
  • GET /v1/operations - Requires operations:read
  • GET /v1/operations/{id} - Requires operations:read
  • GET /v1/environments - Requires org:read

API Key Expiration

API keys can have expiration dates:

  • No expiration - Key is valid until revoked (default)
  • 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.

Authentication Errors

401 Unauthorized

Invalid API key:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Missing API key:

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required"
  }
}

Expired API key:

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "API key has expired"
  }
}

Revoked API key:

{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "API key has been revoked"
  }
}

403 Forbidden

Insufficient scope:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient scope. Required: deployments:write"
  }
}

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

OverviewOperations