Authentication & Access

XnoleX uses JWT-based authentication with refresh token rotation and API key support. This page covers the full authentication lifecycle including registration, login, token management, and API access.

Registration Flow

XnoleX uses an approval-based registration process:

1. User submits registration via POST /onboarding/register
2. Account is created with status pending
3. An admin reviews and approves the account
4. An activation email is sent to the user
5. User sets their password via POST /onboarding/activate
6. Account status becomes active

Login

Authenticate by posting email and password to the login endpoint:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

A successful login returns an access token (15 minute expiry) and a refresh token (7 day expiry):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "user",
    "tier_slug": "demo"
  }
}

JWT Tokens

XnoleX uses the RS256 (RSA Signature with SHA-256) algorithm for signing JWT tokens.

The frontend stores both tokens in localStorage. Access tokens are sent in theAuthorization: Bearer header.

Token Refresh

When the access token expires, use the refresh token to obtain a new token pair. The old refresh token is invalidated upon use (rotation).

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

The frontend handles token refresh automatically. When a request returns a 401 status, the refresh endpoint is called, the tokens are updated, and the original request is retried.

Logout

Logout revokes the current refresh token session, preventing further token refreshes.

curl -X POST http://localhost:8000/api/v1/auth/logout \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIs..."
  }'

Concurrent Sessions

XnoleX limits each user to a maximum of 5 concurrent refresh token sessions. When a new login exceeds this limit, the oldest refresh token session is automatically revoked.

Password Requirements

All passwords must be a minimum of 12 characters. Passwords are hashed using bcrypt via the passlib library and are never stored in plaintext.

API Keys

API keys provide programmatic access for integrations. They are available on Monthly and Yearly plans.

• Format: xnk_{token}
• Stored as SHA-256 hashes — plaintext keys are never persisted
• Optional expiration via expires_in_days
• Granular permissions: ["read", "scan"]

Authenticate with an API key using the X-API-Key header:

curl -H "X-API-Key: xnk_a1b2c3d4e5f6..." \
  http://localhost:8000/api/v1/targets

Roles & Authorization

XnoleX uses role-based access control with two roles:

All resources (targets, scans, schedules, notifications, API keys) are scoped to the creating user. Users can only access and manage their own resources.