Login & sessions
Summary
The four calls, the four errors that account for 95% of the support, and the config knobs.
The four calls
# Login
curl -X POST https://auth.febasi.com.br/api/v1/login \
-H "Content-Type: application/json" \
-d '{ "tenantCode": "acme", "identifier": "alice@acme.com", "password": "Strong-Pass-12!" }'
# Refresh (rotates both tokens)
curl -X POST https://auth.febasi.com.br/api/v1/refresh \
-H "Content-Type: application/json" \
-d '{ "refreshToken": "8c9a3a48-7b9d-..." }'
# Logout (revokes the refresh token)
curl -X POST https://auth.febasi.com.br/api/v1/logout \
-H "Content-Type: application/json" \
-d '{ "refreshToken": "8c9a3a48-7b9d-..." }'
# Whoami (use the access token from /login or /refresh)
curl https://auth.febasi.com.br/api/v1/me \
-H "Authorization: Bearer eyJ..."Common errors
| Code | Status | When | Client action |
|---|---|---|---|
INVALID_CREDENTIALS | 401 | Wrong password, unknown identifier, or inactive user (deliberately ambiguous). | Surface a generic "invalid login" message. |
TOKEN_EXPIRED | 401 | Access token's exp is in the past. | Call /refresh. |
INVALID_TOKEN | 401 | Refresh token revoked, rotated, or malformed. | Force a relogin. |
RATE_LIMIT_EXCEEDED | 429 | Per-IP budget exhausted (/login 5/min, /refresh 10/5min). | Honor Retry-After exactly. |
SESSION_LIMIT_EXCEEDED | 429 | Tenant capped concurrent sessions and configured enforceLogout: false. Includes currentSessions / maxSessions. | Log a different session out first. |
Config knobs (tenant authConfig)
| Path | Default | Effect |
|---|---|---|
tokenConfig.accessTokenExpiration | 900 | Access-token lifetime in seconds (15 min). |
tokenConfig.refreshTokenExpiration | 7 | Refresh-token lifetime in days. |
sessionLimits.maxConcurrentSessions | 5 | Active sessions allowed per user. |
sessionLimits.enforceLogout | true | At the limit: true evicts the oldest; false rejects login with SESSION_LIMIT_EXCEEDED. |
sessionTimeout | 30 | Inactivity timeout in minutes. |
Update via PATCH /api/v1/tenants/:id/config. Existing sessions are not retroactively shortened.
Admin operations
The four token-management calls (list, revoke single, revoke per user, revoke tenant-wide) live in Session management. All four require tokens:read or tokens:revoke and accept dual auth (JWT or Client Key with X-Tenant-Code).