Authentication

How to authenticate with the ReliaPulse API.

Overview

ReliaPulse supports two authentication methods:

1. API Keys - For programmatic access
2. Session Cookies - For browser-based access

API Key Authentication

Creating an API Key

1. Navigate to Settings > API Keys
2. Click "New API Key"
3. Configure:
   • Name: Descriptive identifier
   • Permissions: Select specific or all
   • Expiration: Optional expiry date
4. Click "Create"
5. Copy the key immediately - it won't be shown again

Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are:

• 43 characters long
• Prefixed with sk_live_
• Base64URL encoded random bytes

Using API Keys

Include the key in the Authorization header:

curl -X GET https://your-domain.com/api/v1/components \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

Security

API keys are stored as SHA-256 hashes:

• Original key is never stored
• Cannot be recovered if lost
• Create a new key if compromised

Permissions

Available Permissions

Permission Logic

• Exact match: components:read grants read access
• Write includes read: components:write also grants read
• Wildcard: Coming soon

Checking Permissions

If a request lacks required permissions:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required permission: components:write"
  }
}

Session Authentication

For browser-based applications using the dashboard:

1. User logs in via /auth/login
2. Session cookie is set
3. Cookie is sent with subsequent requests

Session authentication is handled automatically by the browser. No additional headers needed.

Session Endpoints

Dual Authentication

API routes support both methods:

1. Check for Authorization: Bearer header
2. If API key found → validate and use
3. If no API key → check session cookie
4. Return 401 if neither valid

This allows:

• Programmatic access via API keys
• Dashboard access via sessions
• Same endpoints for both

API Key Management

Listing Keys

curl https://your-domain.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_xxx"

Returns keys with metadata (key value is masked):

{
  "data": [
    {
      "id": "key_123",
      "name": "CI/CD Pipeline",
      "lastUsedAt": "2026-01-22T10:00:00Z",
      "expiresAt": null,
      "permissions": ["components:read", "incidents:write"]
    }
  ]
}

Creating Keys

curl -X POST https://your-domain.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Deployment",
    "permissions": ["incidents:write", "components:read"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Response includes the full key (only time it's shown):

{
  "id": "key_456",
  "name": "Production Deployment",
  "key": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permissions": ["incidents:write", "components:read"]
}

Revoking Keys

curl -X DELETE https://your-domain.com/api/v1/api-keys/{id} \
  -H "Authorization: Bearer sk_live_xxx"

Revoked keys stop working immediately.

Public Endpoints

Some endpoints require no authentication:

These endpoints:

• Return only published data
• Are rate limited more strictly
• Don't require any headers

Error Responses

401 Unauthorized

No valid authentication provided:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden

Valid auth but insufficient permissions:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Best Practices

1. Use minimal permissions - Only grant what's needed
2. Rotate keys regularly - Create new keys periodically
3. Use expiration dates - Set expiry for temporary access
4. Monitor usage - Check lastUsedAt for activity
5. Name descriptively - Know what each key is for
6. Revoke unused keys - Clean up old access

Related Documentation

• Settings - Key management UI
• Errors - Error handling
• Rate Limits - Request limits