Authentication in APIs

Every API request to the MATIH Platform (except public endpoints like login) must be authenticated. The platform supports three authentication mechanisms: JWT access tokens for user requests, API keys for programmatic access, and service tokens for inter-service communication.

Authentication Methods

JWT Token Flow

Login

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

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

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJ...",
    "refreshToken": "eyJ...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Token Refresh

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJ..."
}

JWT Claims

The access token carries the following claims:

API Key Authentication

API keys provide long-lived programmatic access:

GET /api/v1/query/execute
Authorization: Bearer <api_key_token>

API keys are managed through the IAM Service:

API key tokens carry restricted permissions (scopes) and are bound to a specific tenant.

Service-to-Service Authentication

When one service calls another, it uses a short-lived service token:

// Generated by JwtTokenProvider
generateServiceToken(serviceName, scopes)
// Lifetime: 5 minutes
// Scopes: limited to the specific operation needed

The service token is included in the Authorization header and carries the originating tenant context.

Authentication Filter Chain

Every request passes through this filter chain in order:

1. SecurityFilter
   - Input validation
   - Attack pattern detection
   - Header sanitization

2. JwtAuthenticationFilter
   - Extract token from Authorization header
   - Validate JWT signature
   - Check token expiration
   - Extract claims (sub, tenant_id, roles)

3. TenantContextFilter
   - Set TenantContextHolder from JWT tenant_id claim
   - Verify X-Tenant-ID header matches JWT claim

4. RbacFilter
   - Check user roles against endpoint permissions
   - Return 403 if insufficient permissions

Public Endpoints

The following endpoints do not require authentication:

Related Pages

• REST Conventions -- URL patterns and headers
• Error Handling -- Authentication error responses
• Security: JWT Tokens -- Detailed token structure and lifecycle
• Security: RBAC -- Role-based access control