API Reference
Overview of the Access Control REST API endpoints and usage patterns.
Authentication
- All endpoints require a Bearer JWT issued by the IDP
- Audience:
control-admin - Include token in Authorization header:
Authorization: Bearer <token>
Base URLs
| Environment | URL |
|---|---|
| Production | https://access-control-api.digiwedge.com |
| UAT | https://access-control-api.uat.digiwedge.com |
| Swagger UI | /api/docs (on the backend) |
Versioning
All endpoints are served under /api/v1/*.
Main Resources
| Resource | Path | Description |
|---|---|---|
| Tenants | /api/v1/tenants | Organization/tenant CRUD operations |
| Users | /api/v1/users | User management |
| User Profiles | /api/v1/user-profiles | Extended user data |
| Sessions | /api/v1/sessions | Session management |
| Login Attempts | /api/v1/login-attempts | Login history |
| Roles | /api/v1/roles | Role CRUD, user-role assignments |
| Features | /api/v1/features | Feature definitions |
| Permissions | /api/v1/permissions | Permission definitions |
| Permission Assignments | /api/v1/permission-assignments | Role-permission mappings |
| Feature Flags | /api/v1/feature-flags | Feature toggles |
| Invitations | /api/v1/invitations | User onboarding workflow |
| Capabilities | /api/v1/capabilities | Permission checks |
Health Endpoints
| Endpoint | Purpose |
|---|---|
/api/health | Liveness check (always returns 200) |
/api/health/ready | Readiness check (checks DB, etc.) |
/metrics | Prometheus metrics |
Required Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <jwt> |
x-tenant-id | Conditional | Tenant UUID for tenant-scoped operations |
Content-Type | POST/PUT/PATCH | application/json |
Error Responses
Standard HTTP status codes:
| Status | Meaning |
|---|---|
| 400 | Bad Request — Invalid input or validation error |
| 401 | Unauthorized — Missing or invalid token |
| 403 | Forbidden — Insufficient permissions |
| 404 | Not Found — Resource doesn't exist |
| 409 | Conflict — Duplicate or conflicting state |
| 500 | Internal Server Error — Unexpected failure |
CORS
The backend allows:
localhost(development)*.digiwedge.comdomains
Additional origins can be configured via CORS_ALLOWED_ORIGINS environment variable (comma-separated).
OpenAPI/Swagger
The full OpenAPI specification is available at /api/docs on the running backend. Use this for:
- Interactive API testing
- Generating client code
- Viewing request/response schemas
TypeScript Client
See API Client for the generated TypeScript client.