Endpoints
The public surface of Febasi Auth — every endpoint a tenant integration may call, grouped by module and required permission.
The Febasi Auth service exposes its API under /api/v1. The same OpenAPI 3.1 specification used to render the Scalar reference at https://auth.febasi.com.br/docs powers the Postman collection shipped with the service.
The Auth column uses three labels:
- Public — no credential required.
- JWT —
Authorization: Bearer <access-token>only. - Dual — JWT or Client Key (
X-API-Key: ck_...) withX-Tenant-Code: <tenant-code>for tenant-scoped operations.
Two surfaces, one document
The tables below cover the tenant-facing surface — everything an external integration uses. A small set of endpoints exists for Febasi platform internals (used by Eved to provision and manage tenants). Those are listed at the bottom for completeness; you do not call them from your application.
Authentication module
| Method | Path | Auth | Permission |
|---|---|---|---|
| POST | /login | Public | — |
| POST | /refresh | Public | — |
| POST | /logout | Public | — |
| POST | /register | Dual | users:create |
| GET | /me | JWT | — |
| POST | /validate | JWT | — |
| GET | /auth/logs | Dual | auth:logs:read |
| GET | /tokens | Dual | tokens:read |
| POST | /tokens/:tokenId/revoke | Dual | tokens:revoke |
| POST | /tokens/revoke-user/:userId | Dual | tokens:revoke |
| POST | /tokens/revoke-all | Dual | tokens:revoke |
See Registration, Login & sessions, and Audit logs.
Users module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /users | Dual | users:read |
| GET | /users/:userId | Dual | users:read |
| PATCH | /users/:userId | Dual | users:update |
| DELETE | /users/:userId | Dual | users:delete |
PATCH /users/:userId accepts updates to email, username, status, emailVerified, and otpEnabled. Passwords are not changed via this endpoint.
Roles module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /roles | Dual | roles:read |
| GET | /roles/:id | Dual | roles:read |
| GET | /roles/:id/permissions | Dual | roles:read |
| POST | /roles | Dual | roles:create |
| PATCH | /roles/:id | Dual | roles:update |
| DELETE | /roles/:id | Dual | roles:delete |
| POST | /roles/assign | Dual | roles:assign |
| POST | /roles/remove | Dual | roles:revoke |
| POST | /roles/:id/permissions | Dual | roles:update |
| DELETE | /roles/:id/permissions | Dual | roles:update |
| GET | /users/:userId/roles | Dual | roles:read |
| GET | /users/:userId/level | Dual | roles:read |
The hierarchy rule applies to every assign/remove call — see Authorization.
Permissions module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /permissions | Dual | permissions:read |
| GET | /permissions/custom | Dual | permissions:read |
| POST | /permissions | Dual | permissions:create |
| PATCH | /permissions/:id | Dual | permissions:update |
| DELETE | /permissions/:id | Dual | permissions:delete |
| POST | /permissions/grant | Dual | permissions:grant |
| POST | /permissions/revoke | Dual | permissions:revoke |
| GET | /permissions/user/:userId | Dual | permissions:read |
| POST | /permissions/check | Dual | — |
POST /permissions/check reads from the database, not the JWT — use it when permission changes need to take effect immediately. Body field is permissionName.
Tenant self-management
These act on your own tenant only. The tenant id you pass is your own — sourced from /tenants/me or from your JWT.
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /tenants/me | Dual | — |
| PATCH | /tenants/:id | JWT | tenants:update |
| PATCH | /tenants/:id/config | JWT | tenants:update |
| GET | /tenants/me/jwt-secret | Dual | tenants:read |
| POST | /tenants/me/jwt-secret/generate | Dual | tenants:update |
| PUT | /tenants/me/jwt-secret | Dual | tenants:update |
| POST | /tenants/me/jwt-secret/rotate | Dual | tenants:update |
| DELETE | /tenants/me/jwt-secret | Dual | tenants:update |
| GET | /tenants/me/metrics | Dual | tenants:read |
| GET | /tenants/me/metrics/logins | Dual | tenants:read |
| GET | /tenants/me/metrics/security | Dual | tenants:read |
PATCH /tenants/:id/config accepts cors, ipAllowlist, passwordPolicy, tokenConfig, sessionLimits, and the other authConfig fields. See CORS configuration and IP allowlist for those blocks.
Updates that would lock the caller out via ipAllowlist are rejected with 400 IP_LOCKOUT_PREVENTED. Append ?force=true to override (logs IP_ALLOWLIST_FORCE_UPDATE to the audit trail).
The JWT-secret endpoints implement secret rotation with a 7-day overlap.
Client Keys module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /client-keys/scopes | Dual | client-keys:read |
| GET | /client-keys/tenant | Dual | client-keys:read |
| GET | /client-keys | JWT | client-keys:read |
| POST | /client-keys | Dual | client-keys:create |
| GET | /client-keys/:id | Dual | client-keys:read |
| PATCH | /client-keys/:id | Dual | client-keys:update |
| POST | /client-keys/:id/revoke | Dual | client-keys:delete |
| GET | /client-keys/:id/logs | Dual | client-keys:read |
| GET | /client-keys/:id/stats | Dual | client-keys:read |
See Integrations → Client Keys.
System endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | Public | Database and routing-pool status. |
| GET | /docs | Public | Interactive Scalar reference for the OpenAPI 3.1 spec. |
Platform-only operations
The endpoints below are reserved for Febasi platform internals — Eved calls them on your behalf when you provision or delete an Auth project. External tenants do not call them; provisioning happens through the Eved Auth project wizard.
| Method | Path | Used by |
|---|---|---|
| POST | /tenants | Eved Auth wizard to create your tenant during onboarding. |
| GET | /tenants | Platform listing — every tenant on the instance. |
| GET | /tenants/stats | Platform-wide statistics. |
| GET | /tenants/search | Platform-wide tenant search. |
| GET | /tenants/:id | Platform read of any tenant (your own is fetched via /tenants/me). |
| DELETE | /tenants/:id | Tenant deletion. |
These exist for completeness but are not part of the tenant-facing contract.