JWT Tokens

JWT (JSON Web Token) authentication is used for user sessions, typically from the dashboard.

Overview

Nexgent uses a two-token system:

Token	Purpose	Expiration
Access Token	Authenticates API requests	15 minutes
Refresh Token	Obtains new access tokens	24 hours (or 30 days with "Remember Me")

Token Structure

Access Token Payload

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "type": "access",
  "jti": "unique-token-id",
  "iat": 1705312200,
  "exp": 1705313100
}

Refresh Token Payload

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "type": "refresh",
  "jti": "unique-token-id",
  "iat": 1705312200,
  "exp": 1705398600
}

Field	Description
`userId`	User's unique identifier
`email`	User's email address
`type`	Token type (`access` or `refresh`)
`jti`	Unique token ID (for blacklisting/rotation)
`iat`	Issued at (Unix timestamp)
`exp`	Expiration (Unix timestamp)

Using Access Tokens

Include the access token in the Authorization header:

curl -X GET https://your-instance.com/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Header Format

Authorization: Bearer <access_token>

Token Lifecycle

Login/Register
      │
      ▼
┌─────────────────────────────────────┐
│  Access Token (15m) + Refresh Token │
└─────────────────────────────────────┘
      │
      ▼
  Use access token for API requests
      │
      ▼
  Access token expires (15m)
      │
      ▼
  Use refresh token to get new tokens
      │
      ▼
  (Repeat until refresh token expires)
      │
      ▼
  Re-login required

Token Expiration

Token	Default	Remember Me
Access Token	15 minutes	15 minutes
Refresh Token	24 hours	30 days

Access token expiration is fixed. The "Remember Me" option only extends the refresh token.

Token Blacklisting

When a user logs out, their access token is immediately blacklisted:

Token jti is stored in Redis
TTL matches remaining token lifetime
Auth middleware checks blacklist on each request

This ensures logged-out tokens cannot be reused.

Security Features

Unique Token IDs (jti)

Every token has a unique ID (jti) enabling:

Token blacklisting on logout
Refresh token rotation (single-use)
Audit trail capabilities

Timing Attack Prevention

Generic Error Messages

Authentication errors use generic messages to prevent email enumeration:

{
  "error": "Invalid email or password"
}

Common Errors

Status	Error	Cause
401	`Authorization header required`	No token provided
401	`Invalid authorization header format`	Not Bearer format
401	`Invalid token`	Malformed or wrong signature
401	`Token expired`	Access token expired
401	`Token has been revoked`	Token blacklisted (logout)

Best Practices

Token Storage

Access Token: Store in memory or secure storage
Refresh Token: Store in httpOnly cookie or secure storage
Never: Store tokens in localStorage (XSS vulnerable)

Token Refresh

Refresh tokens before expiration (e.g., at 14 minutes)
Handle refresh failures gracefully (redirect to login)
Store the new refresh token after each refresh

Logout

Always call the logout endpoint
Clear stored tokens client-side
Optionally send refresh token for explicit revocation

Overview API Keys