Skip to content

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.

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

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.