Skip to main content

Authentication

For Data Analysts

Olytix Core supports multiple authentication methods to secure API access. Choose the method that best fits your use case.

Authentication Methods​

MethodUse CaseSecurity Level
API KeysServer-to-server, scriptsMedium
JWT TokensUser applications, SSOHigh
OAuth 2.0Third-party integrationsHigh

API Keys​

Generating API Keys​

# Via CLI
olytix-core auth create-key --name "My Application" --expires 365d

# Output
API Key Created:
  Key: olytix-core_key_abc123xyz789
  Name: My Application
  Expires: 2025-01-20
  Scopes: read

⚠ Store this key securely. It won't be shown again.

Using API Keys​

Header Authentication (Recommended):

curl -X POST http://localhost:8000/api/v1/query \
  -H "Authorization: Bearer olytix-core_key_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"metrics": ["monthly_revenue"]}'

Query Parameter:

curl "http://localhost:8000/api/v1/query?api_key=olytix-core_key_abc123xyz789"

API Key Scopes​

ScopePermissions
readQuery data, read metadata
writeModify definitions, run models
adminFull access including security
# Create key with specific scopes
olytix-core auth create-key --name "Read Only" --scopes read
olytix-core auth create-key --name "Full Access" --scopes read,write,admin

JWT Tokens​

For user-based authentication:

Getting a Token​

curl -X POST http://localhost:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@company.com",
    "password": "your-password"
  }'

Response:

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

Using JWT Tokens​

curl -X POST http://localhost:8000/api/v1/query \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"metrics": ["monthly_revenue"]}'

Refreshing Tokens​

curl -X POST http://localhost:8000/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "refresh_abc123..."
  }'

OAuth 2.0​

For third-party integrations:

Configuration​

# olytix-core_project.yml
security:
  oauth:
    enabled: true
    providers:
      - name: google
        client_id: ${GOOGLE_CLIENT_ID}
        client_secret: ${GOOGLE_CLIENT_SECRET}
        authorize_url: https://accounts.google.com/o/oauth2/auth
        token_url: https://oauth2.googleapis.com/token

OAuth Flow​

  1. Redirect user to authorization URL
  2. User authenticates with provider
  3. Provider redirects back with code
  4. Exchange code for access token
  5. Use token for API requests

Error Responses​

401 Unauthorized​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication"
  }
}

Causes:

  • Missing Authorization header
  • Invalid API key
  • Expired token

403 Forbidden​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this resource"
  }
}

Causes:

  • API key lacks required scope
  • User lacks required role
  • Resource access denied by RLS

Best Practices​

  1. Never expose API keys in client-side code
  2. Use environment variables for keys
  3. Rotate keys regularly
  4. Use minimal required scopes
  5. Monitor API key usage

Next Steps​