Authentication
Secure your API requests with JWT bearer tokens.
Overview
CyberOrigen uses JSON Web Tokens (JWT) for API authentication. All requests to protected endpoints must include a valid token.
Obtaining a Token
Login Endpoint
bash
POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded
username=[email protected]&password=yourpasswordResponse
json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}cURL Example
bash
curl -X POST https://backend.cyberorigen.com/api/v1/auth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "[email protected]&password=yourpassword"Using Tokens
Include the token in the Authorization header:
bash
curl https://backend.cyberorigen.com/api/v1/scans \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Token Refresh
Tokens expire after 1 hour. Refresh before expiration:
bash
POST /api/v1/auth/refresh
Authorization: Bearer YOUR_CURRENT_TOKENResponse:
json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}API Keys
Professional and Enterprise
API keys are available on Professional and Enterprise plans.
For automated systems, use API keys instead of user credentials:
Create an API Key
- Go to Settings > API Keys
- Click Generate New Key
- Set permissions and expiration
- Copy the key (shown only once)
Using API Keys
bash
curl https://backend.cyberorigen.com/api/v1/scans \
-H "X-API-Key: YOUR_API_KEY"API Key Permissions
| Permission | Description |
|---|---|
read:scans | View scan results |
write:scans | Create and manage scans |
read:findings | View vulnerability findings |
write:findings | Update finding status |
read:grc | View GRC data |
write:grc | Modify controls and evidence |
MFA for API Access
When MFA is enabled, initial token requests require the MFA code:
bash
POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded
username=[email protected]&password=yourpassword&mfa_code=123456Session Management
List Active Sessions
bash
GET /api/v1/auth/sessionsRevoke a Session
bash
DELETE /api/v1/auth/sessions/{session_id}Revoke All Sessions
bash
POST /api/v1/auth/logout-allSecurity Best Practices
- Never expose tokens in client-side code or version control
- Use API keys for automated systems instead of user credentials
- Rotate API keys regularly
- Set appropriate expiration for API keys
- Use minimum permissions required for your integration
Error Responses
Invalid Credentials
json
{
"detail": "Incorrect email or password",
"error_code": "INVALID_CREDENTIALS"
}Expired Token
json
{
"detail": "Token has expired",
"error_code": "TOKEN_EXPIRED"
}Invalid Token
json
{
"detail": "Could not validate credentials",
"error_code": "INVALID_TOKEN"
}MFA Required
json
{
"detail": "MFA code required",
"error_code": "MFA_REQUIRED"
}