Authentication

Getting a token

curl -X POST https://api.mael.in/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Send the access token on every subsequent request:

curl https://api.mael.in/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token lifetimes

Token	Default lifetime	Notes
Access token	30 minutes	HS256, carries `jti` for revocation checks
Refresh token	7 days	Single-use — each refresh rotates and denies the consumed `jti`

Refreshing

curl -X POST https://api.mael.in/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

Returns a new access/refresh pair. The consumed refresh token is denied — reusing it (e.g. a stolen, already-rotated token) fails, which is what makes rotation meaningful rather than cosmetic.

Logging out

curl -X POST https://api.mael.in/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Denies the current access token’s jti immediately, rather than waiting out its natural expiry.

How the dashboard differs

If you’re calling the API directly (scripts, integrations, this documentation’s examples), you manage the access/refresh tokens yourself as shown above. The dashboard (apps/dashboard) does not — it keeps the refresh token in an httpOnly cookie set by its own Next.js route handlers, which are the only code that ever sees one. If you’re building against the dashboard’s own routes rather than the public API directly, see Security for that design.

Password reset

curl -X POST https://api.mael.in/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Issues a single-use, hashed, time-limited reset token (60 minutes by default). Completing the reset (/auth/reset-password) invalidates every other active session for that user.

Super admin

Platform operators use a super_admin account (tenant_id is NULL) and the X-Tenant-ID header to act on a specific tenant. super_admin access tokens are additionally checked against a Redis denylist on every request, so they can be revoked before their natural expiry — see Security.

API Reference

API Endpoints

Authentication

Getting a token

Token lifetimes

Refreshing

Logging out

How the dashboard differs

Password reset

Super admin

Errors

​Getting a token

​Token lifetimes

​Refreshing

​Logging out

​How the dashboard differs

​Password reset

​Super admin

Errors

Getting a token

Token lifetimes

Refreshing

Logging out

How the dashboard differs

Password reset

Super admin