Authentication

Authentication

Complete guide to authenticating with the Overwatch API using JWT tokens, API keys, and SSO.

Authentication Methods

JWT Tokens

Best for: User sessions, interactive applications

• Short-lived access tokens (1 hour)
• Refresh tokens for renewal
• User-scoped permissions
• SSO integration support

API Keys

Best for: Service integrations, automation

• Long-lived credentials
• Configurable permissions
• IP whitelist support
• Usage monitoring

JWT Authentication

Login and Obtain Token

Request:

curl -X POST "https://your-org.overwatch.com/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@company.com&password=your-password"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Using Access Token

Include the access token in the Authorization header:

curl -X GET "https://your-org.overwatch.com/api/v1/incidents" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Refresh

Refresh the access token before it expires:

curl -X POST "https://your-org.overwatch.com/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

Response:

{
  "access_token": "new-access-token",
  "token_type": "bearer",
  "expires_in": 3600
}

Logout

Invalidate current session and tokens:

curl -X POST "https://your-org.overwatch.com/api/v1/auth/logout" \
  -H "Authorization: Bearer your-token"

API Key Authentication

Generate API Key

Create an API key via dashboard or API:

curl -X POST "https://your-org.overwatch.com/api/v1/api-keys" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Integration",
    "permissions": [
      "incidents:read",
      "incidents:create",
      "procedures:execute"
    ],
    "ip_whitelist": ["10.0.0.0/8"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "id": "key-uuid",
  "name": "CI/CD Integration",
  "api_key": "overwatch_ak_1234567890abcdef",
  "permissions": ["incidents:read", "incidents:create", "procedures:execute"],
  "created_at": "2025-10-15T10:30:00Z",
  "expires_at": "2026-12-31T23:59:59Z"
}

Store Securely

The API key is only displayed once. Store it securely in your secrets manager.

Using API Key

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

curl -X GET "https://your-org.overwatch.com/api/v1/incidents" \
  -H "X-API-Key: overwatch_ak_1234567890abcdef"

List API Keys

View all API keys for your organization:

curl -X GET "https://your-org.overwatch.com/api/v1/api-keys" \
  -H "Authorization: Bearer your-token"

Revoke API Key

Revoke an API key immediately:

curl -X DELETE "https://your-org.overwatch.com/api/v1/api-keys/{key_id}" \
  -H "Authorization: Bearer your-token"

SSO Authentication

Supported Providers

• Azure Active Directory (Azure AD)
• Okta
• Google Workspace
• OneLogin
• SAML 2.0 (generic)

SSO Flow

1. Initiate SSO

   curl -X GET "https://your-org.overwatch.com/api/v1/auth/sso/initiate?provider=azure"

2. User Authenticates

   • User redirected to SSO provider
   • User logs in with SSO credentials
   • SSO provider redirects back with auth code

3. Handle Callback

   curl -X POST "https://your-org.overwatch.com/api/v1/auth/sso/callback" \
     -H "Content-Type: application/json" \
     -d '{"code": "auth-code", "state": "state-value"}'

4. Receive JWT Token

   • API returns JWT access and refresh tokens
   • Use tokens for subsequent requests

Permission Model

Permission Scopes

Format: resource:action

Incidents

Permission	Description
incidents:read	View incidents
incidents:create	Create new incidents
incidents:update	Update incident details
incidents:delete	Delete incidents
incidents:assign	Assign incidents to users

Procedures

Permission	Description
procedures:read	View procedures
procedures:create	Create new procedures
procedures:update	Update procedure definitions
procedures:delete	Delete procedures
procedures:execute	Execute procedures
procedures:approve	Approve procedure execution

Analytics

Permission	Description
analytics:read	View analytics data
analytics:export	Export analytics reports

Settings

Permission	Description
settings:read	View settings
settings:update	Update configuration

Users

Permission	Description
users:read	View user profiles
users:create	Create new users
users:update	Update user details
users:delete	Delete users
users:manage	Full user management

API Key Configuration

Permission Restrictions:

{
  "name": "DevOps API Key",
  "permissions": [
    "incidents:*",           // All incident operations
    "procedures:read",       // Read procedures only
    "procedures:execute"     // Execute procedures
  ],
  "ip_whitelist": [
    "10.0.0.0/8",           // Corporate network
    "172.16.0.0/12"         // VPN network
  ],
  "rate_limit": 10000,      // Custom rate limit
  "expires_at": "2026-12-31T23:59:59Z"
}

Get Current User

Retrieve current user profile and permissions:

curl -X GET "https://your-org.overwatch.com/api/v1/auth/me" \
  -H "Authorization: Bearer your-token"

Response:

{
  "id": "user-uuid",
  "email": "user@company.com",
  "name": "John Doe",
  "role": "engineer",
  "organization": {
    "id": "org-uuid",
    "name": "Acme Corporation"
  },
  "permissions": [
    "incidents:read",
    "incidents:create",
    "procedures:read",
    "procedures:execute"
  ],
  "last_login": "2025-10-15T10:30:00Z"
}

Security Best Practices

Token Management

1. Store Securely: Use environment variables or secrets manager
2. Rotate Regularly: Rotate API keys every 90 days
3. Limit Scope: Grant minimum necessary permissions
4. Monitor Usage: Review API key usage regularly
5. Revoke Unused: Remove API keys no longer in use

JWT Best Practices

1. Short Expiration: Access tokens expire in 1 hour
2. Refresh Tokens: Use refresh tokens to obtain new access tokens
3. Secure Storage: Store tokens in secure, httpOnly cookies or memory
4. Logout on Exit: Invalidate tokens when user logs out
5. Handle Expiration: Implement token refresh logic

API Key Best Practices

1. IP Whitelisting: Restrict API keys to known IP ranges
2. Separate Keys: Use different keys for different services
3. Monitor Alerts: Set up alerts for unusual usage patterns
4. Audit Logs: Review API key usage in audit logs
5. Emergency Revocation: Have process to quickly revoke compromised keys

Authentication Errors

Common Error Responses

401 Unauthorized - Invalid Token:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "JWT token has expired",
    "details": {
      "expired_at": "2025-10-15T09:30:00Z"
    }
  }
}

401 Unauthorized - Invalid API Key:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key not found or revoked"
  }
}

403 Forbidden - Insufficient Permissions:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "User does not have permission to perform this action",
    "details": {
      "required_permission": "incidents:delete",
      "user_permissions": ["incidents:read", "incidents:create"]
    }
  }
}

SDK Examples

JavaScript

const { OverwatchClient } = require('@overwatch/api-client');

// Using JWT
const client = new OverwatchClient({
  baseURL: 'https://your-org.overwatch.com',
  username: 'user@company.com',
  password: 'your-password'
});

await client.login();

// Using API Key
const clientWithKey = new OverwatchClient({
  baseURL: 'https://your-org.overwatch.com',
  apiKey: 'overwatch_ak_1234567890abcdef'
});

// Automatic token refresh
client.on('token.expired', async () => {
  await client.refresh();
});

Python

from overwatch import OverwatchClient

# Using JWT
client = OverwatchClient(
    base_url='https://your-org.overwatch.com',
    username='user@company.com',
    password='your-password'
)

client.login()

# Using API Key
client_with_key = OverwatchClient(
    base_url='https://your-org.overwatch.com',
    api_key='overwatch_ak_1234567890abcdef'
)

# Automatic token refresh
client.auto_refresh = True

Next Steps

• Incidents API - Incident management endpoints
• Procedures API - Runbook automation endpoints
• Error Handling - Error responses and rate limits
• WebSocket API - Real-time updates

Need Help?

For authentication issues, contact support@overwatch-observability.com.

---

Related Documentation:

• User Management - Managing user accounts
• RBAC - Role-based access control
• Security - Security policies