Authentication
CHAD supports two authentication methods: JWT tokens for browser sessions and API keys for programmatic access.
JWT Authentication
Used by the web UI for user sessions.
Login
POST /api/auth/login
Content-Type: application/json
{
"username": "user@example.com",
"password": "your-password"
}
{
"access_token": "eyJ...",
"token_type": "bearer",
"user": {
"id": "abc-123",
"username": "user@example.com",
"role": "analyst"
}
}
Using JWT Token
Include in Authorization header:
curl -H "Authorization: Bearer eyJ..." \
https://chad.example.com/api/rules
Token Expiration
Tokens expire after 8 hours by default. Refresh by logging in again.
Logout
Clears the session cookie.
API Key Authentication
Recommended for external integrations.
Using API Keys
Include in Authorization header:
curl -H "Authorization: Bearer chad_ak_xxxxx..." \
https://chad.example.com/api/external/alerts
API Key Endpoints
API keys use dedicated external endpoints:
| Internal | External |
|---|
/api/alerts | /api/external/alerts |
/api/rules | /api/external/rules |
/api/stats | /api/external/stats |
Creating API Keys
POST /api/api_keys
Authorization: Bearer <jwt-token>
Content-Type: application/json
{
"name": "My Integration"
}
{
"id": "key-123",
"name": "My Integration",
"key": "chad_ak_xxxxx...",
"created_at": "2024-01-15T14:32:17Z"
}
The key value is only returned once. Store it securely.
Two-Factor Authentication
If 2FA is enabled, login requires a second step.
Initial Login
POST /api/auth/login
Content-Type: application/json
{
"username": "user@example.com",
"password": "your-password"
}
{
"requires_2fa": true,
"temp_token": "temp_xxx..."
}
Complete 2FA
POST /api/auth/2fa/verify
Content-Type: application/json
{
"temp_token": "temp_xxx...",
"code": "123456"
}
{
"access_token": "eyJ...",
"token_type": "bearer"
}
CSRF Protection
State-changing requests require CSRF token.
Get CSRF Token
Response:
{
"csrf_token": "abc123..."
}
Include CSRF Token
POST /api/rules
X-CSRF-Token: abc123...
Content-Type: application/json
{...}
SSO Authentication
When SSO is enabled:
Initiate SSO
GET /api/auth/sso/login?provider=oidc
SSO Callback
GET /api/auth/sso/callback?code=xxx&state=yyy
Error Responses
401 Unauthorized
{
"detail": "Could not validate credentials"
}
- Missing authentication
- Expired token
- Invalid API key
403 Forbidden
{
"detail": "Not enough permissions"
}
- User role insufficient
- API key read-only
- Resource access denied
CHAD includes security headers:
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
Best Practices
- Use API keys for integrations, not user credentials
- Rotate API keys periodically
- Use HTTPS only
- Store credentials securely
- Monitor for authentication failures
Next Steps
