Skip to Content
DocsAPI ReferenceAuthentication

Authentication

Quazzar has two separate authentication systems: one for the Cloud OS API on each instance and one for the Control Panel API. Both use JWT bearer tokens, but they differ in setup flow, token management, and additional auth methods.

Cloud OS Authentication

The Cloud OS runs on a single server and has a single admin user. Authentication uses JWT tokens, optional TOTP-based two-factor authentication, and API keys for programmatic access.

Initial Setup

On first boot, the Cloud OS has no user configured. You must create the admin account by calling the setup endpoint:

curl -X POST http://localhost:8080/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "YourSecurePassword123"
  }'
{
  "message": "Setup complete",
  "user": {
    "id": "usr_abc123",
    "username": "admin",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

The setup endpoint is only available when no user exists. After the initial admin account is created, this endpoint returns 409 Conflict. Keep your admin credentials in a secure location.

Login

Authenticate with the admin credentials to receive a JWT token pair:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "YourSecurePassword123"
  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

If TOTP two-factor authentication is enabled, the login response indicates that a TOTP code is required:

{
  "totp_required": true,
  "temp_token": "eyJhbGciOiJIUzI1NiIs..."
}

Complete the login by verifying the TOTP code:

curl -X POST http://localhost:8080/api/auth/totp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "temp_token": "eyJhbGciOiJIUzI1NiIs...",
    "code": "123456"
  }'

Returns the standard token pair on success.

Using the Token

Include the access token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Refresh

Access tokens are short-lived. Use the refresh token to obtain a new access token without re-authenticating:

curl -X POST http://localhost:8080/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Get Current User

Verify the current authenticated user:

curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer <access_token>"

Change Password

curl -X POST http://localhost:8080/api/auth/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword123",
    "new_password": "NewSecurePassword456"
  }'

Two-Factor Authentication (TOTP)

Enable TOTP-based 2FA for the admin account:

curl -X POST http://localhost:8080/api/auth/totp/enable \
  -H "Authorization: Bearer <access_token>"

Returns a provisioning URI and QR code data. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password) and then verify with a code to activate:

curl -X POST http://localhost:8080/api/auth/totp/verify \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Session Management

List all active sessions:

curl http://localhost:8080/api/auth/sessions \
  -H "Authorization: Bearer <access_token>"

Revoke a specific session:

curl -X DELETE http://localhost:8080/api/auth/sessions/session_abc123 \
  -H "Authorization: Bearer <access_token>"

API Keys

API keys provide long-lived credentials for scripts, CI/CD pipelines, and integrations. All Cloud OS API keys use the qzr_ prefix and are signed with HMAC-SHA256.

Create an API Key:

curl -X POST http://localhost:8080/api/keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "expires_in_days": 90
  }'
{
  "id": "key_abc123",
  "name": "CI Pipeline Key",
  "key": "qzr_abc123def456...",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-04-15T10:30:00Z"
}

Copy the API key immediately. The full key value is only shown once at creation time. If you lose it, you must create a new key.

Use an API Key:

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer qzr_abc123def456...

List API Keys:

curl http://localhost:8080/api/keys \
  -H "Authorization: Bearer <access_token>"

Revoke an API Key:

curl -X DELETE http://localhost:8080/api/keys/key_abc123 \
  -H "Authorization: Bearer <access_token>"

API keys have full admin access to the Cloud OS instance. Treat them like passwords: store them in a secrets manager and never commit them to version control.

Control Panel Authentication

The Control Panel is a multi-tenant SaaS platform. Each user belongs to a tenant (organization), and all API requests are scoped to the authenticated user’s tenant.

Registration

Create a new account on the Control Panel:

curl -X POST https://panel.quazzar.cloud/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd",
    "name": "Jane Doe"
  }'
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Jane Doe",
  "tenant_id": "ten_abc123",
  "created_at": "2025-01-15T10:30:00Z"
}

Login

curl -X POST https://panel.quazzar.cloud/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd"
  }'
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "tenant_id": "ten_abc123"
}

If TOTP is enabled for the user, the response will include totp_required: true and a temp_token. Complete login by verifying the TOTP code, same as the Cloud OS flow.

Using the Token

Include the access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

All requests are automatically scoped to the authenticated user’s tenant. You cannot access resources belonging to other tenants.

Get Current User

curl https://panel.quazzar.cloud/api/auth/me \
  -H "Authorization: Bearer <access_token>"

Update Profile

curl -X PUT https://panel.quazzar.cloud/api/auth/profile \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith"
  }'

Change Password

curl -X POST https://panel.quazzar.cloud/api/auth/change-password \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword",
    "new_password": "NewSecurePassword"
  }'

TOTP Two-Factor Authentication

The Control Panel supports TOTP 2FA with the same enable and verify flow as the Cloud OS. Enable TOTP through the Control Panel settings or via the API.

Authentication Summary

FeatureCloud OS APIControl Panel API
Token typeJWT BearerJWT Bearer
Initial setupPOST /api/auth/setupPOST /api/auth/register
LoginPOST /api/auth/loginPOST /api/auth/login
Token refreshPOST /api/auth/refreshPOST /api/auth/refresh
TOTP 2FASupportedSupported
API keysYes (qzr_ prefix, HMAC-SHA256)No
Multi-userSingle adminMulti-tenant
ScopeFull instance accessTenant-scoped

Next Steps

  • Cloud OS API — use your Cloud OS credentials to manage apps and system resources
  • Control Panel API — use your Control Panel credentials to manage fleet and billing
API OverviewCloud OS API