title: "Authentication API Reference" description: "Reference documentation for Navius Authentication API endpoints, request/response formats, and integration patterns" category: "Reference" tags: ["api", "authentication", "security", "jwt", "oauth", "endpoints"] last_updated: "April 9, 2025" version: "1.0"

Authentication API Reference

Overview

The Navius Authentication API provides endpoints for user authentication, token management, and session control. It supports multiple authentication methods including JWT-based authentication, OAuth2 with Microsoft Entra, and API key authentication.

This reference document details all endpoints, data structures, and integration patterns for implementing authentication in Navius applications.

Authentication Methods

Navius supports the following authentication methods:

Method	Use Case	Security Level	Configuration
JWT	General purpose authentication	High	Required JWT secret
Microsoft Entra	Enterprise authentication	Very High	Requires tenant configuration
API Keys	Service-to-service	Medium	Requires key management
Session Cookies	Web applications	Medium-High	Requires session configuration

API Endpoints

User Authentication

`POST /auth/login`

Authenticates a user and returns a JWT token.

Request Body:

{
  "username": "[email protected]",
  "password": "secure_password"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Error Responses:

401 Unauthorized: Invalid credentials
403 Forbidden: Account locked or disabled
429 Too Many Requests: Rate limit exceeded

Curl Example:

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"secure_password"}'

Code Example:

#![allow(unused)]
fn main() {
// Client-side authentication request
async fn login(client: &Client, username: &str, password: &str) -> Result<TokenResponse> {
    let response = client
        .post("http://localhost:3000/auth/login")
        .json(&json!({
            "username": username,
            "password": password
        }))
        .send()
        .await?;
        
    if response.status().is_success() {
        Ok(response.json::<TokenResponse>().await?)
    } else {
        Err(format!("Authentication failed: {}", response.status()).into())
    }
}
}

`POST /auth/refresh`

Refreshes an expired JWT token using a refresh token.

Request Body:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Error Responses:

401 Unauthorized: Invalid refresh token
403 Forbidden: Refresh token revoked

`POST /auth/logout`

Invalidates the current session or token.

Request Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response (200 OK):

{
  "message": "Successfully logged out"
}

Microsoft Entra Integration

`GET /auth/entra/login`

Initiates Microsoft Entra authentication flow.

Query Parameters:

redirect_uri (required): URL to redirect after authentication
state (optional): State parameter for CSRF protection

Response:

Redirects to Microsoft Entra login page.

`GET /auth/entra/callback`

Callback endpoint for Microsoft Entra authentication.

Query Parameters:

code (required): Authorization code from Microsoft Entra
state (optional): State parameter for CSRF protection

Response:

Redirects to the original redirect_uri with token information.

API Key Management

`POST /auth/apikeys`

Creates a new API key for service-to-service authentication.

Request Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body:

{
  "name": "Service Integration Key",
  "permissions": ["read:users", "write:data"],
  "expiresIn": 2592000  // 30 days in seconds
}

Response (201 Created):

{
  "id": "api_123456789",
  "key": "sk_live_abcdefghijklmnopqrstuvwxyz123456789",
  "name": "Service Integration Key",
  "permissions": ["read:users", "write:data"],
  "createdAt": "2025-04-09T10:15:30Z",
  "expiresAt": "2025-05-09T10:15:30Z"
}

Data Models

TokenResponse

#![allow(unused)]
fn main() {
/// Response containing authentication tokens
struct TokenResponse {
    /// JWT access token
    token: String,
    
    /// JWT refresh token
    refresh_token: String,
    
    /// Token validity in seconds
    expires_in: u64,
    
    /// Token type (always "Bearer")
    token_type: String,
}
}

ApiKey

#![allow(unused)]
fn main() {
/// API key for service-to-service authentication
struct ApiKey {
    /// Unique identifier
    id: String,
    
    /// Secret key (only returned on creation)
    key: Option<String>,
    
    /// Display name
    name: String,
    
    /// List of permissions
    permissions: Vec<String>,
    
    /// Creation timestamp
    created_at: DateTime<Utc>,
    
    /// Expiration timestamp
    expires_at: DateTime<Utc>,
}
}

Integration Patterns

JWT Authentication Flow

Client calls /auth/login with credentials
Server validates credentials and returns JWT + refresh token
Client stores tokens and includes JWT in subsequent requests
When JWT expires, client uses refresh token to get a new JWT
For logout, client calls /auth/logout and discards tokens

#![allow(unused)]
fn main() {
// Server-side handler for protected routes
async fn protected_route(
    auth: AuthExtractor,
    // other parameters
) -> Result<impl IntoResponse> {
    // Auth middleware extracts and validates JWT automatically
    // If JWT is invalid, route is not reached
    
    // Access authenticated user
    let user_id = auth.user_id;
    
    // Access user permissions
    if !auth.has_permission("read:resource") {
        return Err(AppError::forbidden("Insufficient permissions"));
    }
    
    // Handle the actual request
    Ok(Json(/* response data */))
}
}

Microsoft Entra (OAuth2) Flow

Redirect user to /auth/entra/login with appropriate parameters
User authenticates with Microsoft
Microsoft redirects to /auth/entra/callback
Server validates the code and issues JWT tokens
Application uses the JWT tokens as in the standard JWT flow

#![allow(unused)]
fn main() {
// Client-side Entra redirect
fn redirect_to_entra_login(redirect_uri: &str) -> String {
    format!(
        "/auth/entra/login?redirect_uri={}&state={}", 
        urlencoding::encode(redirect_uri),
        generate_random_state()
    )
}
}

API Key Authentication

Administrator creates API key via /auth/apikeys
Service includes API key in requests via header
Server validates API key and permissions
For security, rotate keys periodically

#![allow(unused)]
fn main() {
// Including API key in request header
let response = client
    .get("http://api.example.com/resource")
    .header("X-API-Key", "sk_live_abcdefghijklmnopqrstuvwxyz123456789")
    .send()
    .await?;
}

Configuration

Authentication can be configured in config/auth.yaml:

auth:
  jwt:
    secret: "${JWT_SECRET}"
    expiration: 3600  # 1 hour
    refresh_expiration: 2592000  # 30 days
  
  entra:
    tenant_id: "${ENTRA_TENANT_ID}"
    client_id: "${ENTRA_CLIENT_ID}"
    client_secret: "${ENTRA_CLIENT_SECRET}"
    redirect_uri: "http://localhost:3000/auth/entra/callback"
  
  api_keys:
    enabled: true
    max_per_user: 10
    default_expiration: 2592000  # 30 days

Best Practices

Security Recommendations

Use HTTPS: Always use HTTPS for all authentication endpoints
Token Storage: Store tokens securely (use HttpOnly cookies for web apps)
Short Expiration: Keep JWT tokens short-lived (1 hour or less)
Refresh Token Rotation: Issue new refresh tokens with each refresh
API Key Handling: Treat API keys as sensitive credentials
Permission Validation: Always validate permissions, not just authentication

Common Pitfalls

JWT in LocalStorage: Avoid storing JWTs in localStorage (vulnerable to XSS)
Missing CSRF Protection: Always use state parameter with OAuth flows
Hardcoded Secrets: Never hardcode secrets in client-side code
Skipping Validation: Always validate JWTs, even in internal services
Weak Tokens: Ensure proper entropy in tokens and use proper algorithms

Troubleshooting

Common Issues

"Invalid token" errors: Check token expiration and signature algorithm
CORS errors: Ensure authentication endpoints have proper CORS configuration
Refresh token not working: Verify refresh token hasn't expired or been revoked
Rate limiting: Check if you're hitting rate limits on authentication endpoints

Debugging

Enable detailed authentication logs by setting:

RUST_LOG=navius::auth=debug

This will show detailed information about token validation, including reasons for rejection.

Navius Documentation