Authentication

Dimebia uses JWT (JSON Web Tokens) for authentication. This guide covers the authentication flow, token management, and security best practices.

Authentication Methods

Dimebia supports two authentication methods:

1. JWT Access Tokens: For user-facing applications (admin UI, merchant portal)
2. API Keys (SK): For server-to-server integrations

JWT Authentication Flow

┌─────────┐      POST /api/user/login       ┌─────────┐
│ Client  │ ──────────────────────────────► │  API    │
│         │ ◄────────────────────────────── │         │
└─────────┴     { accessToken,             └─────────┘
                 refreshToken }
       │
       │  Authorization: Bearer <accessToken>
       ▼
┌─────────┐      API Request               ┌─────────┐
│ Client  │ ──────────────────────────────► │  API    │
│         │ ◄────────────────────────────── │         │
└─────────┴       Response                  └─────────┘

Login

POST /api/user/login

{
  "account": "demo",
  "password": "password123"
}

Response

{
  "code": 200,
  "message": "Login success",
  "data": {
    "token": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "expiresIn": 86400,
      "tokenType": "Bearer"
    },
    "userType": "PLATFORM_ADMIN",
    "tenantId": null,
    "deploymentMode": "private",
    "userName": "demo",
    "userId": 1
  }
}

Using Access Tokens

Include the access token in the Authorization header:

curl -X GET http://localhost:8080/api/user/info \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refresh Tokens

Access tokens expire after 24 hours (default). Use the refresh token to get a new access token:

POST /api/user/refresh

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

Token Structure

JWT tokens contain the following claims:

{
  "sub": "1",
  "username": "demo",
  "roles": ["admin", "user"],
  "tenantId": "tenant_123",
  "userType": "PLATFORM_ADMIN",
  "iat": 1724000000,
  "exp": 1724086400
}

Claim	Description
sub	User ID
username	Username
roles	List of user roles
tenantId	Tenant ID (SaaS mode)
userType	User type enum
iat	Issued at (Unix timestamp)
exp	Expiration (Unix timestamp)

User Types

Type	Description	Access
PLATFORM_ADMIN	Platform administrator	Full access to all tenants and admin features
MERCHANT_ADMIN	Merchant administrator	Full access to own tenant
MERCHANT_USER	Merchant user	Limited access based on roles

Password Management

Password Requirements

• Minimum length: 6 characters
• Recommended: 12+ characters with mixed case, numbers, and symbols
• Stored using BCrypt (strength 10)

Forgot Password

POST /api/user/forgot-password

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

Reset Password

POST /api/user/reset-password

{
  "token": "reset-token-from-email",
  "newPassword": "newSecurePassword123"
}

API Key Authentication

For server-to-server integrations, use API keys:

curl -X POST http://localhost:8080/api/transaction/create \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey sk_live_abcdefghijklmnopqrstuvwxyz0123456789"

Security Best Practices

1. Store tokens securely: Use HTTP-only cookies or secure storage
2. Never log tokens: Avoid logging access tokens or refresh tokens
3. Use HTTPS: Always use TLS in production
4. Implement token refresh: Handle token expiration gracefully
5. Short-lived tokens: Keep access token lifetime minimal
6. Rotate secrets: Regularly rotate JWT secrets

Token Expiration

Token Type	Default TTL	Config
Access Token	24 hours	app.jwt.access-token-expire
Refresh Token	7 days	app.jwt.refresh-token-expire

Logout

POST /api/user/logout

Client-side: Remove tokens from storage.

localStorage.removeItem('token');
localStorage.removeItem('refreshToken');