Web Authentication

Overview

NetKey implements a two-token authentication system following OAuth 2.0 best practices:

Authentication Flow

1. Login

When a user logs in with username/password:

{
  "username": "user@example.com",
  "password": "your-password",
  "remember_me": true
}

Response includes:

• Access token in the JSON response body
• Refresh token set as an HttpOnly cookie
• User information (role, group, permissions)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": 1,
    "username": "user@example.com",
    "role": "GROUP_ADMIN",
    "group_id": 3,
    "group_name": "Acme Corp"
  }
}

Set-Cookie: refresh_token=abc123...; HttpOnly; Secure; SameSite=Lax; Max-Age=1209600; Path=/api/auth

2. Using the Access Token

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

3. Refreshing the Access Token

When the access token expires (after 1 hour), use the refresh token to get a new one. The refresh token is automatically sent via the HttpOnly cookie.

// No body required - refresh token is in the cookie
fetch('/api/auth/refresh', {
  method: 'POST',
  credentials: 'include'  // Important: sends cookies
});

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

Set-Cookie: refresh_token=new_token...; HttpOnly; Secure; ...

4. Logout

Logout invalidates both the access token and refresh token:

fetch('/api/auth/logout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken
  },
  credentials: 'include'
});

Token Details

Access Token (JWT) Payload

The access token is a standard JWT containing:

Token Lifetimes

Security Features

Multi-Factor Authentication

NetKey supports TOTP-based MFA (compatible with Google Authenticator, Authy, etc.). When MFA is enabled, the login flow requires an additional step:

// Step 1: Initial login returns requires_mfa
{
  "requires_mfa": true,
  "mfa_type": "totp"
}

// Step 2: Submit with TOTP code
POST /api/auth/login
{
  "username": "user@example.com",
  "password": "your-password",
  "totp_code": "123456"
}

API Keys vs JWT

For programmatic access (integrations, scripts, automation), use API Keys instead of JWT tokens. See the API Reference for details.

Error Responses