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

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=yourpassword

Response

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

cURL Example

curl -X POST https://backend.cyberorigen.com/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=yourpassword"

Using Tokens

Include the token in the Authorization header:

curl https://backend.cyberorigen.com/api/v1/scans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Refresh

Tokens expire after 1 hour. Refresh before expiration:

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_CURRENT_TOKEN

Response:

{
  "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

1. Go to Settings > API Keys
2. Click Generate New Key
3. Set permissions and expiration
4. Copy the key (shown only once)

Using API Keys

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:

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=yourpassword&mfa_code=123456

Session Management

List Active Sessions

GET /api/v1/auth/sessions

Revoke a Session

DELETE /api/v1/auth/sessions/{session_id}

Revoke All Sessions

POST /api/v1/auth/logout-all

Security Best Practices

1. Never expose tokens in client-side code or version control
2. Use API keys for automated systems instead of user credentials
3. Rotate API keys regularly
4. Set appropriate expiration for API keys
5. Use minimum permissions required for your integration

Error Responses

Invalid Credentials

{
  "detail": "Incorrect email or password",
  "error_code": "INVALID_CREDENTIALS"
}

Expired Token

{
  "detail": "Token has expired",
  "error_code": "TOKEN_EXPIRED"
}

Invalid Token

{
  "detail": "Could not validate credentials",
  "error_code": "INVALID_TOKEN"
}

MFA Required

{
  "detail": "MFA code required",
  "error_code": "MFA_REQUIRED"
}