API Authentication

External API clients authenticate with a Bearer JWT. Mobile apps receive a JWT on login and refresh it automatically. Web sessions use cookies.

Obtain a token (mobile / server-to-server)

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

{
  "email": "you@example.com",
  "password": "your-password"
}

// Response
{
  "ok": true,
  "token": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 3600
}

Refresh a token

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

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

// Response
{
  "ok": true,
  "token": "eyJ...",
  "expiresIn": 3600
}

Use the token

GET /api/inbox
Authorization: Bearer eyJ...

Token lifetime

• Access tokens expire after 1 hour.
• Refresh tokens expire after 30 days.
• Refresh tokens are rotated on use (each refresh issues a new refresh token).

Revoke a token

POST /api/auth/logout
Authorization: Bearer eyJ...

Next steps

• Send your first email via API →