Mobile Authentication API

The NogLog mobile app uses token-based authentication with JWT access and refresh tokens. This is separate from the web app's session-based authentication to provide a better mobile experience.

Overview

Mobile authentication uses a dual token system:

• Access Token: Short-lived (15 minutes), used for API requests
• Refresh Token: Long-lived (7 days), used to obtain new access tokens

Tokens are stored securely on the device using Capacitor Preferences (EncryptedSharedPreferences on Android).

Endpoints

POST /api/auth/mobile/login

Authenticate a user and receive access/refresh tokens.

Request Body:

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

Success Response (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "username": "username",
    "role": "USER",
    "isEmailVerified": true
  }
}

Error Responses:

• 400 - Missing email or password
• 401 - Invalid credentials
• 403 - Account suspended
• 429 - Rate limit exceeded

---

POST /api/auth/mobile/register

Create a new account and receive access/refresh tokens.

Request Body:

{
  "email": "user@example.com",
  "username": "myusername",
  "password": "SecurePass123!"
}

Success Response (201):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "username": "myusername",
    "role": "USER",
    "isEmailVerified": false
  },
  "message": "Account created successfully. Please check your email to verify your account."
}

Validation Rules:

• Email: Must be valid format, unique
• Username: 3-30 characters, alphanumeric and underscores only, unique
• Password: Minimum 8 characters, must contain uppercase, lowercase, and number

Error Responses:

• 400 - Invalid input or validation failed
• 409 - Email or username already exists
• 429 - Rate limit exceeded

---

POST /api/auth/mobile/refresh

Exchange a refresh token for new access and refresh tokens.

Request Body:

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

Or send the refresh token in the Authorization header:

Authorization: Bearer <refreshToken>

Success Response (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "username": "username",
    "role": "USER",
    "isEmailVerified": true
  }
}

Error Responses:

• 400 - Missing refresh token
• 401 - Invalid or expired refresh token
• 403 - Account suspended
• 429 - Rate limit exceeded

---

Using Access Tokens

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

Authorization: Bearer <accessToken>

Example:

const response = await fetch('https://api.noglog.app/api/brands', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
});

Note: The mobile app uses a dedicated API subdomain (api.noglog.app) to avoid CORS redirect issues.

Token Refresh Flow

The mobile app automatically refreshes tokens before they expire:

1. Store expiresIn value when tokens are received
2. Set a timer to refresh ~1 minute before expiration
3. Call /api/auth/mobile/refresh with the current refresh token
4. Store the new tokens and update the timer

If refresh fails with 401, prompt the user to log in again.

Rate Limiting

All mobile auth endpoints are rate-limited:

• Login: 5 attempts per IP per 15 minutes
• Register: 3 attempts per IP per hour
• Refresh: 10 attempts per IP per 15 minutes

Rate limit headers are included in responses:

• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Unix timestamp when limit resets

Token Claims

Access tokens contain the following claims:

{
  "id": "user-uuid",
  "email": "user@example.com",
  "username": "username",
  "role": "USER",
  "isEmailVerified": true,
  "type": "access",
  "iat": 1234567890,
  "exp": 1234568790
}

Refresh tokens have type: "refresh" and a longer expiration.

Security Considerations

1. Token Storage: Always use secure storage (Capacitor Preferences) for tokens
2. HTTPS: All requests must use HTTPS in production
3. Token Rotation: Refresh tokens are rotated on each refresh
4. Logout: Clear stored tokens on logout
5. Flagged Accounts: Suspended accounts receive 403 and should logout