Endpoints
The complete public surface of Febasi Auth, grouped by module, with required permissions.
The Auth exposes 42 documented endpoints under /api/v1, organized
into six modules. The same OpenAPI 3.1 specification used to render the
Swagger UI at https://auth.febasi.com.br/docs powers the Postman collection
shipped with the service.
The tables below are a navigational map. For request/response shapes, authentication semantics, and error handling, follow the relevant guide.
Authentication module
| Method | Path | Auth | Permission |
|---|---|---|---|
| POST | /login | Public | — |
| POST | /refresh | Public | — |
| POST | /logout | JWT | — |
| POST | /register | Public | — |
| GET | /me | JWT | — |
| POST | /validate | JWT | — |
| GET | /auth-logs | JWT | auth:logs |
See Login flow in depth and Refresh tokens & rotation.
Users module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /users | JWT / Key | users:read |
| GET | /users/:userId | JWT / Key | users:read |
| PATCH | /users/:userId | JWT / Key | users:update |
| DELETE | /users/:userId | JWT / Key | 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 | JWT / Key | roles:read |
| GET | /roles/:id | JWT / Key | roles:read |
| GET | /roles/:id/permissions | JWT / Key | roles:read |
| POST | /roles | JWT / Key | roles:create |
| PATCH | /roles/:id | JWT / Key | roles:update |
| DELETE | /roles/:id | JWT / Key | roles:delete |
| POST | /roles/assign | JWT / Key | roles:assign |
| POST | /roles/remove | JWT / Key | roles:revoke |
| POST | /roles/:id/permissions | JWT / Key | roles:update |
| DELETE | /roles/:id/permissions | JWT / Key | roles:update |
The hierarchy rule applies to every assign/remove call — see Authorization.
Permissions module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /permissions | JWT / Key | permissions:read |
| GET | /permissions/custom | JWT / Key | permissions:read |
| POST | /permissions | JWT / Key | permissions:create |
| PATCH | /permissions/:id | JWT / Key | permissions:update |
| DELETE | /permissions/:id | JWT / Key | permissions:delete |
| POST | /permissions/grant | JWT / Key | permissions:grant |
| POST | /permissions/revoke | JWT / Key | permissions:revoke |
| GET | /permissions/user/:userId | JWT / Key | permissions:read |
| POST | /permissions/check | JWT / Key | — |
POST /permissions/check reads from the database, not the JWT — use it
when permission changes need to take effect immediately.
Tenants module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /tenants | JWT / Key | tenants:read |
| POST | /tenants | JWT / Key | tenants:create |
| GET | /tenants/:id | JWT / Key | tenants:read |
| GET | /tenants/me | JWT | — |
| PATCH | /tenants/:id | JWT / Key | tenants:update |
| DELETE | /tenants/:id | JWT / Key | tenants:delete |
| PATCH | /tenants/:id/config | JWT / Key | tenants:update |
| GET | /tenants/me/config | JWT | — |
| POST | /tenants/me/jwt-secret/generate | JWT | tenants:update |
| GET | /tenants/me/jwt-secret | JWT | tenants:read |
| POST | /tenants/me/jwt-secret/set | JWT | tenants:update |
| POST | /tenants/me/jwt-secret/clear | JWT | tenants:update |
| GET | /tenants/me/metrics | JWT / Key | tenants:read |
| GET | /tenants/me/metrics/security | JWT / Key | tenants:read |
| PUT | /tenants/:id/database | JWT / Key | tenants:update |
| GET | /tenants/search | JWT / Key | tenants:read |
The JWT-secret endpoints implement secret rotation with a 7-day overlap.
Client Keys module
| Method | Path | Auth | Permission |
|---|---|---|---|
| GET | /client-keys/scopes | JWT / Key | — |
| GET | /client-keys/tenant | JWT / Key | — |
| GET | /client-keys | JWT / Key | admin:* |
| POST | /client-keys | JWT / Key | client-keys:create |
| GET | /client-keys/:id | JWT / Key | client-keys:read |
| PATCH | /client-keys/:id | JWT / Key | client-keys:update |
| POST | /client-keys/:id/revoke | JWT / Key | client-keys:revoke |
| GET | /client-keys/:id/logs | JWT / Key | client-keys:read |
| GET | /client-keys/:id/stats | JWT / Key | client-keys:read |
See Client Keys (service-to-service auth).
System endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | Public | Database and routing-pool status. |
| GET | /docs | Public | Interactive Swagger UI for the OpenAPI 3.1 spec. |