Home / API / Authentication

Authentication API

Secure user authentication with JWT tokens, two-factor authentication, and API key management.

🔐 Base URL

https://api.datixlab.com/v1/auth

📍 Endpoints

Register User

Create a new user account.

Request

POST /register

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "full_name": "John Doe",
  "organization_name": "Acme Corp"
}

Response - 201 Created

{
  "id": "user_123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "organization_id": "org_456",
  "role": "admin",
  "created_at": "2024-12-15T10:00:00Z"
}

Errors

Login

Authenticate and receive JWT access token.

Request

POST /login

Request Body

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Response - 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "admin",
    "organization_id": "org_456",
    "two_factor_enabled": false
  }
}

Response with 2FA Enabled

{
  "requires_2fa": true,
  "temp_token": "temp_xyz789"
}

Errors

Verify 2FA

Complete login with two-factor authentication code.

Request

POST /verify-2fa

Request Body

{
  "temp_token": "temp_xyz789",
  "code": "123456"
}

Response - 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "admin"
  }
}

Enable 2FA

Enable two-factor authentication for current user.

Request

POST /enable-2fa
Authorization: Bearer <access_token>

Response - 200 OK

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "backup_codes": [
    "12345678",
    "23456789",
    "34567890",
    "45678901",
    "56789012",
    "67890123",
    "78901234",
    "89012345",
    "90123456",
    "01234567"
  ]
}

Confirm 2FA Setup

Verify 2FA setup by providing a code.

Request

POST /confirm-2fa
Authorization: Bearer <access_token>

Request Body

{
  "code": "123456"
}

Response - 200 OK

{
  "success": true,
  "message": "Two-factor authentication enabled"
}

Disable 2FA

Disable two-factor authentication.

Request

POST /disable-2fa
Authorization: Bearer <access_token>

Request Body

{
  "password": "SecurePass123!",
  "code": "123456"
}

Response - 200 OK

{
  "success": true,
  "message": "Two-factor authentication disabled"
}

Refresh Token

Get a new access token before expiration.

Request

POST /refresh
Authorization: Bearer <access_token>

Response - 200 OK

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

Logout

Invalidate current access token.

Request

POST /logout
Authorization: Bearer <access_token>

Response - 200 OK

{
  "success": true,
  "message": "Logged out successfully"
}

🔑 API Keys

Generate API Key

Create a new API key for programmatic access.

Request

POST /api-keys
Authorization: Bearer <access_token>

Request Body

{
  "name": "Production API Key",
  "description": "For production integrations",
  "expires_in_days": 365
}

Response - 201 Created

{
  "id": "key_abc123",
  "name": "Production API Key",
  "key": "sk_live_xyz789...",
  "created_at": "2024-12-15T10:00:00Z",
  "expires_at": "2025-12-15T10:00:00Z"
}
Important

The API key is only shown once. Store it securely.

List API Keys

GET /api-keys
Authorization: Bearer <access_token>

Response - 200 OK

{
  "api_keys": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "key_prefix": "sk_live_xyz...",
      "created_at": "2024-12-15T10:00:00Z",
      "expires_at": "2025-12-15T10:00:00Z",
      "last_used_at": "2024-12-16T08:30:00Z"
    }
  ]
}

Revoke API Key

DELETE /api-keys/{key_id}
Authorization: Bearer <access_token>

Response - 200 OK

{
  "success": true,
  "message": "API key revoked"
}

👤 User Profile

Get Current User

GET /me
Authorization: Bearer <access_token>

Response - 200 OK

{
  "id": "user_123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "role": "admin",
  "organization_id": "org_456",
  "two_factor_enabled": true,
  "assigned_agents": ["agent_abc", "agent_def"],
  "created_at": "2024-01-15T10:00:00Z"
}

Update Profile

PATCH /me
Authorization: Bearer <access_token>

Request Body

{
  "full_name": "John Smith",
  "email": "john.smith@example.com"
}

Change Password

POST /change-password
Authorization: Bearer <access_token>

Request Body

{
  "current_password": "OldPass123!",
  "new_password": "NewPass456!"
}

🔒 Security Best Practices

✅ Use HTTPS

Always use HTTPS for API requests

✅ Store Tokens Securely

Use secure storage, not localStorage

✅ Rotate API Keys

Generate new keys regularly

✅ Enable 2FA

Require 2FA for all users

✅ Monitor Usage

Track API key usage and anomalies

✅ Set Expiration

API keys should have expiration dates

📝 Code Examples

Python

import requests

# Login
response = requests.post(
    'https://api.datixlab.com/v1/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'SecurePass123!'
    }
)

data = response.json()
access_token = data['access_token']

# Make authenticated request
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(
    'https://api.datixlab.com/v1/agents',
    headers=headers
)

JavaScript

// Login
const response = await fetch('https://api.datixlab.com/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        email: 'user@example.com',
        password: 'SecurePass123!'
    })
});

const { access_token } = await response.json();

// Make authenticated request
const agentsResponse = await fetch('https://api.datixlab.com/v1/agents', {
    headers: { 'Authorization': `Bearer ${access_token}` }
});

🚀 Next Steps

Next: Queries API →