Reference¶
Generated from the OpenAPI files and the SDK's TypeScript doc comments at build time, so they match the code at the same commit.
HTTP APIs¶
Every page below has its raw OpenAPI file next to it (api/<name>.yaml, for example
api/platform.yaml), with the bearer security scheme declared, for client
generators.
- Platform API: capabilities, effective access, grants, organization,
superadmin operations (module enable/disable, platform-role grant and revoke), metrics.
Generated from
internal/gateway/platform-openapi.yaml. - Notification
- DocShare (
docs) - Helpdesk
- Timesheet
Every response uses one envelope: { "data": … } on success, { "error": { "code", "message",
"details"? } } on failure. Error codes are stable strings (AUTH_TOKEN_MISSING, FORBIDDEN,
MODULE_DISABLED, AUTHORIZATION_UNAVAILABLE, …). The sample modules' OpenAPI files omit some
status codes their handlers emit (see limitations).
What the gateway mounts¶
Every route family, in one place. Everything under /api/ needs a bearer unless noted.
| Family | Routes | Who |
|---|---|---|
/api/platform/* |
GET capabilities, GET capabilities/{module}, GET catalog; POST admin/apps; POST admin/modules/{key}/enable, .../disable; POST admin/platform-roles, DELETE admin/platform-roles/{role}/{subjectId}; GET/PUT admin/mfa-policy/global, GET/PUT/DELETE admin/mfa-policy/users/{subject}, POST admin/mfa-policy/sync; GET metrics; GET demo-mode (no bearer) |
Any user for reads; superadmin for admin/* and metrics |
/api/auth/effective-access/* |
POST can, POST batch-can, GET summary?companyId= |
Any user, for the bearer only |
/api/auth/grants |
POST (grant or revoke tuples) |
Superadmin, or a registered app's backend (service-client token) on its own types |
/api/org/me/companies |
GET |
Any user |
/api/org/companies/{id}/members |
GET ?q=&page=&pageSize= |
Active members of the company that are not guests, or a superadmin |
/api/org/companies/{id}/positions |
GET ?page=&pageSize= |
Active members of the company that are not guests, or a superadmin: id, code, title |
/api/org/companies/{id}/groups |
GET ?page=&pageSize= |
Active members of the company that are not guests, or a superadmin: id, code, name of active groups |
/api/org/companies/{id}/members/by-subject/{subject} |
GET |
Superadmin, or a registered app's backend |
/api/org/companies/{id}/positions/{positionId}/holder |
GET ?date=YYYY-MM-DD |
Active members of the company that are not guests, or a superadmin |
/api/org/companies/{id}/groups/{groupId}/members |
GET |
Active members of the company that are not guests, or a superadmin |
/api/org/admin/units* |
POST units, GET units/{id}, GET units/{id}/subtree |
Superadmin |
/api/org/admin/* (members, positions, assignments, groups) |
GET/POST members (isGuest), PUT members/{id} (isGuest), POST/DELETE members/{id}/link-user; GET/POST companies/{id}/positions, PUT positions/{id}, POST positions/{id}/assignments, POST positions/{id}/handover, POST assignments/{id}/end; GET/POST companies/{id}/groups, GET/POST groups/{id}/members, DELETE groups/{id}/members/{memberId} |
Superadmin, or an administrator of that company |
/api/<module>/v1/* |
Forwarded to the module unchanged, once it is installed and enabled | The module decides |
/auth/*, /realms/*, /resources/* |
Keycloak, without a bearer; /auth/admin* and the master realm answer 404 |
Browser login |
/ |
The sample shell |
Companies, org units and members are created through /api/org/admin/*; see
Integrate your app.
SDKs¶
- SDK guide: the browser SDK (install, session, clients, recipes, errors) and the Node backend entry
- SDK API reference: TypeScript, browser and
serverentries - Recipes:
canI,grantObjectAccess,revokeObjectAccess - Python:
sdk/python(kiban-sdk) - Go:
github.com/rosschiu/kiban/sdk
Contributing¶
- Contributing: setup, gates, conventions, licensing of contributions
Metrics¶
See the Metrics page. Each service exposes Prometheus metrics; the gateway's GET /api/platform/metrics requires a
superadmin bearer. kiban_build_info{version,commit} identifies the build.