Authentication

Two Authentication Methods

BlueSentinel uses two authentication mechanisms:

1. JWT Bearer Tokens — For admin dashboard and API clients
2. API Key + Device ID — For endpoint agents

Admin Authentication (JWT)

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "admin@bluesentinel.com",
  "password": "your-password"
}

Response (200):

{
  "user": {
    "id": "uuid",
    "email": "admin@bluesentinel.com",
    "name": "Admin",
    "role": "super_admin",
    "tenant_id": "uuid"
  },
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}

Using the Token

Include the JWT in the Authorization header for all admin API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Token Properties

• Algorithm: HS256
• Expiry: 12 hours
• Payload: sub (user ID), email, role, tenant_id

Current User

GET /api/auth/me
Authorization: Bearer <token>

Returns the current user's details.

Logout

POST /api/auth/logout
Authorization: Bearer <token>

Agent Authentication (API Key)

After enrollment, agents authenticate using two headers on every request:

X-API-Key: <48-byte-urlsafe-token>
X-Device-ID: <device-uuid>
X-Agent-Version: 1.0.0
Content-Type: application/json

How API Keys Work

• During enrollment, the server generates a 48-byte URL-safe token
• The token is returned to the agent once and never stored in plaintext
• The server stores a SHA-256 hash of the token
• On every request, the server hashes the provided X-API-Key and compares it to the stored hash

Key Security

• API keys are generated using secrets.token_urlsafe(48)
• Lost keys cannot be recovered — the device must be re-enrolled
• Retired devices have their API keys invalidated

Enrollment Authentication

The enrollment endpoint uses a one-time enrollment token instead of API keys:

POST /api/v1/enroll
Content-Type: application/json

{
  "enrollment_token": "abc123..."
}

Enrollment tokens are generated by admins in the dashboard and have configurable expiry and max-use limits.