Authentication

The Controlinfra API supports multiple authentication methods depending on the use case.

JWT Tokens

JWT tokens are issued on login or OAuth callback and are used for browser-based sessions.

Obtaining a token:

curl -X POST https://api.controlinfra.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "user@example.com",
    "role": "user"
  }
}

Using the token:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.controlinfra.com/api/scans/dashboard

Token Refresh

Refresh an expired JWT using the refresh token:

curl -X POST https://api.controlinfra.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIs..."}'

GitHub OAuth

OAuth authentication redirects through GitHub and issues a JWT on callback.

1. Redirect the user to GET /api/auth/github
2. GitHub authenticates and redirects to /api/auth/github/callback
3. The callback issues a JWT and redirects to the frontend

CLI OAuth Flow

For CLI authentication, pass cli=true and a localhost redirect_uri:

GET /api/auth/github?cli=true&redirect_uri=http://127.0.0.1:9876/callback

The callback redirects to the local CLI server with the token.

CLI API Tokens

CLI tokens are long-lived tokens with granular scope-based permissions. They are prefixed with ci_.

Creating a CLI token:

curl -X POST https://api.controlinfra.com/api/auth/cli-tokens \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "scopes": ["repos:read", "scans:read", "scans:trigger"],
    "allRepositories": true
  }'

Response:

{
  "token": "ci_abc123...",
  "name": "CI Pipeline",
  "scopes": ["repos:read", "scans:read", "scans:trigger"],
  "allRepositories": true
}

WARNING

The full token value is only returned once at creation time. Store it securely.

Available Scopes

Scope	Description
repos:read	List and view repository configurations
repos:write	Create, update, delete repository configurations
scans:read	List and view scan results
scans:trigger	Trigger and cancel scans
drifts:read	List and view drift details
drifts:write	Update drift status, generate fixes, create PRs
runners:read	List and view runner details
runners:manage	Create, update, delete runners

Request Signing (Optional)

CLI tokens support optional HMAC-SHA256 request signing for enhanced security:

Header	Description
x-cli-signature	HMAC-SHA256 signature
x-cli-timestamp	Unix timestamp (ms)
x-cli-nonce	Unique request nonce

Signature format:

HMAC-SHA256(timestamp:nonce:METHOD:path:bodyHash, token)

Where bodyHash is SHA256(JSON.stringify(body)).

Timestamps must be within 5 minutes of the server time. Nonces are tracked to prevent replay attacks.

Runner Tokens

Self-hosted runners authenticate using a runner-specific token sent via the X-Runner-Token header.

curl -X POST https://api.controlinfra.com/api/runners/heartbeat \
  -H "X-Runner-Token: <runner-token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "online", "version": "1.0.0"}'

Runner tokens are generated when creating a runner and can be regenerated via the API.

Service Account Tokens

For CI/CD systems, a service account token can be obtained using a service key:

curl -X POST https://api.controlinfra.com/api/auth/service-token \
  -H "Content-Type: application/json" \
  -H "x-service-key: <service-key>"

Download Tokens

Short-lived tokens for download endpoints (e.g., runner install scripts):

curl -X POST https://api.controlinfra.com/api/auth/download-token \
  -H "Authorization: Bearer <jwt-token>"