Skip to content

Integrate your app

Your application runs beside Kiban and keeps its own code, database and deployment. This page connects it: the backend registers the app and talks to Kiban through an SDK, the frontend logs users in through Kiban. It is written as numbered steps; each step says what to run and what you should see.

Which track

  • Backend track: a Node, Python or Go backend (or any language with the REST API) that needs to know who the user is, ask "may they do this here?", and record who may see what.
  • Frontend track: a browser application that needs login and the same question for its UI.
  • Administration: creating the first company and its members, as a superadmin.
  • REST-only: the routes behind the SDKs, for any language.

Read this before you start

Three things 0.1 does not do. They shape the steps below.

  1. Registering an app, enabling it, and creating companies are superadmin work. A company's administrator manages that company's members, positions, assignments and groups (Administration); there is no self-service registration.
  2. Checks answer for the bearer only. Your backend asks with the user's own token ("may this user") or its service token ("may I"). There is no "list every object this user may see" API yet.
  3. An app is enabled for the whole deployment, not per company.

Every track assumes a running Kiban. make dev from a checkout gives you a gateway at https://127.0.0.1:8443; the image quickstart gives you http://localhost:3000. See the Quickstart. The samples use tokidesk as the app key; use your own.

Backend track

The Node samples on this page are compiled and run against the SDK by its test suite; the Go samples compile with the Go SDK; the same calls run end to end against a real stack in the repository's live tests.

1. Give your backend a service client

Add a client id to KIBAN_SERVICE_CLIENTS in .env (comma-separated) and start the stack; bootstrap creates a confidential Keycloak client with a service account and the kiban-api audience. Read its secret in the Keycloak admin console: realm kiban, Clients, tokidesk-backend, Credentials.

KIBAN_SERVICE_CLIENTS=tokidesk-backend

You should see service client tokidesk-backend: applied in bootstrap's log on the first run and converged afterwards.

2. Write the manifest

One JSON document: the app key, the service client, the feature keys your code will ask about, and the object types and relations your app owns. Every object type declares company_module (the anchor that binds an object to a company) plus its own relations. Registration does not check for the anchor; see limitations.

{
  "key": "tokidesk",
  "displayName": "TokiDesk",
  "version": "1.0.0",
  "serviceClientId": "tokidesk-backend",
  "features": ["tokidesk.ticket.view", "tokidesk.ticket.edit", "tokidesk.reminders.run"],
  "authzFragment": {
    "ticket": {
      "company_module": { "this": true },
      "viewer": { "this": true },
      "editor": { "this": true }
    }
  }
}

Relations follow the base model's grammar (this, computedUserset, tupleToUserset, union, intersection); the Building page documents it. A type the base model or another app already declares is refused.

3. Register and enable the app

As a superadmin (the token from Getting a token for the shell), once:

curl -sk https://127.0.0.1:8443/api/platform/admin/apps \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" -d @manifest.json
curl -sk -X POST https://127.0.0.1:8443/api/platform/admin/modules/tokidesk/enable \
  -H "Authorization: Bearer $TOKEN"

You should see {"data":{"module":"tokidesk","installed":true,"enabled":false,...}} from the first call and "enabled":true from the second. Registering again updates the app in place (the version is stored, not compared); a bad manifest is a 422 naming the field. No restart happens; the gateway recognises the app's service client within about five seconds. Each backend SDK also has the registration call (registerApp, register_app, RegisterApp), which takes a superadmin's bearer and the manifest.

4. Install the SDK

npm i @rossbsol/kiban-sdk

The backend entry is @rossbsol/kiban-sdk/server (ESM, Node 20 or later, no runtime dependencies). Published to the public npm registry; see the SDK guide.

pip install kiban-sdk           # or, from a checkout: pip install ./sdk/python

Python 3.10 or later; depends on PyJWT with its cryptography extra.

go get github.com/rosschiu/kiban/sdk

5. Create the client once at startup

import { createAppClient, createServiceCredentials, createTokenVerifier } from "@rossbsol/kiban-sdk/server";

const gatewayOrigin = "https://127.0.0.1:8443";
const credentials = createServiceCredentials({ gatewayOrigin, clientId: "tokidesk-backend", clientSecret });
const kiban = createAppClient({ gatewayOrigin, appKey: "tokidesk", credentials });
const verifier = createTokenVerifier({ gatewayOrigin });
from kiban import KibanClient

kiban = KibanClient(gateway_url="https://127.0.0.1:8443", client_id="tokidesk-backend", client_secret=SECRET)
kiban, err := sdk.New(ctx, sdk.Config{GatewayURL: "https://127.0.0.1:8443", ClientID: "tokidesk-backend", ClientSecret: secret})

You should see no network call yet in Node and Python; the Go client fetches the realm's signing keys at construction and fails loudly if the gateway is unreachable.

The make dev gateway serves a self-signed certificate, which Node, Python and Go reject until your backend trusts it (NODE_EXTRA_CA_CERTS for Node, SSL_CERT_FILE for Python and Go, or your own sdk.Config.HTTPClient in Go). The image quickstart's http://localhost:3000 has no certificate to trust.

6. Verify the user's token on every request

Your frontend sends the user's Kiban access token as Authorization: Bearer. Verify it before anything else: signature against the realm's keys, issuer, audience, expiry. The subject you get back is who the user is and nothing more; never read a role from the token.

export async function requireUser(authorization: string | undefined): Promise<string> {
  const bearer = authorization?.replace(/^Bearer /, "");
  if (!bearer) throw new Error("login required");
  const user = await verifier.verify(bearer);
  return user.subject;
}
def require_user(authorization: str | None) -> str:
    bearer = (authorization or "").removeprefix("Bearer ")
    if not bearer:
        raise PermissionError("login required")
    return kiban.verify_user_token(bearer).subject   # raises jwt.PyJWTError otherwise
func requireUser(ctx context.Context, kiban *sdk.Client, r *http.Request) (string, error) {
    bearer := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
    if bearer == "" {
        return "", errors.New("login required")
    }
    return kiban.VerifyUserToken(ctx, bearer)
}

You should see the user's sub (their Keycloak id) for a valid token and an error for an expired one, one for another audience, or one Kiban did not sign.

A verified token says who the user was when it was issued, nothing more. It does not know that the user has since been disabled in Keycloak or deactivated in the company. Only a decision (step 7) checks that, on every call. So make a decision before serving data, and never treat a verified token alone as "still allowed". A disabled user's token verifies until it expires, KIBAN_ACCESS_TOKEN_LIFESPAN seconds, 300 by default.

Recommendation: verify the token locally, then ask for a decision, on every request, in one helper.

Why. The token proves identity and nothing else. Verifying it is a signature check against the realm's keys, local and free, and that is all it can ever tell you: who this was when the token was issued. Whether the user may do something now is a different question with a different answer over time. A user is disabled, leaves a company, loses a position, has a share revoked. None of that changes the token. Only a decision asks identity and org for the user's current state, so only a decision refuses a disabled user on their next request rather than when the token expires. Kiban's own routes work the same way, except the few listed in limitations. Verifying first still matters: it rejects forged, expired and foreign tokens before anything touches Kiban, and gives you the subject for logging.

How. Decide on every request, including routes with nothing to protect. "My profile" or "my tickets" has no object, but it has a feature key, and a decision on the feature key alone is what refuses a disabled user there. Put the two halves in one helper and start every handler with it, so a route cannot verify and forget to decide:

export async function requireAccess(req: Request, featureKey: string, companyId: string,
                                    object?: { type: string; id: string }, relation?: string) {
  const bearer = req.headers.authorization?.replace(/^Bearer /, "");
  if (!bearer) throw new Error("login required");
  await verifier.verify(bearer);                       // who: local, free
  const decision = await kiban.can(bearer, {           // whether: Kiban, every call
    featureKey, moduleKey: "tokidesk", scope: "company", companyId, object, relation
  });
  if (!decision.allowed) throw new Error("forbidden: " + decision.reason);
  return bearer;
}
def require_access(authorization, feature_key, company_id, object=None, relation=None):
    bearer = (authorization or "").removeprefix("Bearer ")
    if not bearer:
        abort(401)
    kiban.verify_user_token(bearer)                          # who: local, free
    decision = kiban.can(bearer, feature_key, module_key="tokidesk", company_id=company_id,
                         object=object, relation=relation)  # whether: Kiban, every call
    if not decision.allowed:
        abort(403)
    return bearer
func requireAccess(ctx context.Context, kiban *sdk.Client, r *http.Request, req sdk.CanRequest) (string, error) {
    bearer := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")
    if bearer == "" {
        return "", errUnauthenticated
    }
    if _, err := kiban.VerifyUserToken(ctx, bearer); err != nil { // who: local, free
        return "", errUnauthenticated
    }
    d, err := kiban.Can(ctx, bearer, req) // whether: Kiban, every call
    if err != nil || !d.Allowed {
        return "", errForbidden
    }
    return bearer, nil
}

Every handler then starts with that one call, and the window for a disabled user is the time between two of their requests, not the token's lifetime.

7. Ask before every read and write

One call with the user's own bearer: the feature key, your app key, the company, and for an object read or write, the object and the relation. A denial is a normal answer with a reason, never an exception.

const decision = await kiban.can(bearer, {
  featureKey: "tokidesk.ticket.view", moduleKey: "tokidesk", scope: "company", companyId,
  object: { type: "ticket", id: ticketId }, relation: "viewer"
});
if (!decision.allowed) return res.status(403).end();
decision = kiban.can(bearer, "tokidesk.ticket.view", module_key="tokidesk", company_id=company_id,
                     object={"type": "ticket", "id": ticket_id}, relation="viewer")
if not decision.allowed:
    abort(403)
d, err := kiban.Can(ctx, bearer, sdk.CanRequest{
    FeatureKey: "tokidesk.ticket.view", ModuleKey: "tokidesk", CompanyID: companyID,
    Object: &struct{ Type string `json:"type"`; ID string `json:"id"` }{"ticket", ticketID}, Relation: "viewer",
})

You should see allowed: true for a member of the company who holds viewer on the ticket, COMPANY_MEMBERSHIP_REQUIRED for someone who is not a member of the company, ENGINE_DENIED for a member who does not hold viewer (or when the ticket has no anchor), MODULE_DISABLED while the app is not enabled, and a 422 for a feature key your manifest does not declare.

8. Write tuples when things happen

When your app creates an object, write its anchor and its first relation in one call, with the app's service token (the SDK obtains and refreshes it). The anchor binds the object to the company; without it every check on the object is denied.

await kiban.grant(companyId, [
  kiban.anchorTuple("ticket", ticketId, companyId),
  { objectType: "ticket", objectId: ticketId, relation: "viewer", subjectType: "user", subjectId: creatorSubject }
]);
kiban.grant(company_id, [
    kiban.anchor_tuple("tokidesk", "ticket", ticket_id, company_id),
    {"objectType": "ticket", "objectId": ticket_id, "relation": "viewer", "subjectType": "user", "subjectId": creator},
])
err := kiban.Grant(ctx, companyID,
    sdk.AnchorTuple("tokidesk", "ticket", ticketID, companyID),
    sdk.Tuple{ObjectType: "ticket", ObjectID: ticketID, Relation: "viewer", SubjectType: "user", SubjectID: creatorSubject},
)

A grant is idempotent: granting a tuple that exists writes nothing. Your database and Kiban are two commits; Module inside or app beside gives the order to write them in and the sweep that reconciles a crash between them.

revoke removes what grant wrote. When your app deletes an object, revoke its anchor: every other tuple on the object goes with it, in the same transaction, each recorded in the ledger. Anchoring the same id again starts from nothing. You should see 403 AUTHORIZATION_DENIED if you name another enabled app's or module's object type: outside its own types an app's backend needs the company's admin relation (company:<id>#admin), and a service account that is only a member of the company (step 10) is refused with reason COMPANY_ROLE_REQUIRED. A base type such as company, or a type no enabled app declares, is 422 VALIDATION_FAILED. A subject can also be a position (subjectType: "position", subjectRelation: "holder") or a group (subjectType: "group", subjectRelation: "member"), so access follows the chair or the membership. The position, group or member must belong to the same company; another company's is 422 VALIDATION_FAILED, and a check in this company never resolves through it. Without the subjectRelation the tuple is stored and never matches.

9. Look the member up

The subject is enough for tuples. When your app needs the member id (to store beside its own rows), ask org whether the subject is an active member of the company. The answer carries the id only; names come from the member directory (step 11).

const fact = await kiban.memberBySubject(companyId, subject);   // { isMember, isActive, memberId }
fact = kiban.member_by_subject(company_id, subject)              # MemberFact(is_member, is_active, member_id)
fact, err := kiban.MemberBySubject(ctx, companyID, subject)

10. Background jobs

A worker, a connector or a mailer has no user. It asks for itself, with the service token. The service account is a user like any other, only its sign-in differs, so it is authorized the same way: it must be a member of the company it acts in, and it gets what was granted to it. Until an administrator makes it a member, every check for it in that company answers COMPANY_MEMBERSHIP_REQUIRED. Enabling the app means "this app exists in this deployment"; membership means "this app's service account may act here". Both are deliberate.

Make the service account a member once per company, with the two admin calls from Administration: create a member for it, then link the member to the service account's subject (the sub of a service token; the account must have made one request through the gateway first, which any check does). The directory then lists it with kind: "service", so a staff list can leave it out.

curl -sk https://127.0.0.1:8443/api/org/admin/members -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"companyId":"<company>","code":"TOKIDESK","displayName":"TokiDesk (reminders)"}'
curl -sk https://127.0.0.1:8443/api/org/admin/members/<memberId>/link-user -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kcSub":"<service account sub>"}'

Writing tuples on the app's own types needs no membership (the owner rule in step 8): that is the app defining its own model, not acting in the company.

const decision = await kiban.canService({ featureKey: "tokidesk.reminders.run", moduleKey: "tokidesk", scope: "company", companyId });
decision = kiban.can_service("tokidesk.reminders.run", module_key="tokidesk", company_id=company_id)
d, err := kiban.CanService(ctx, sdk.CanRequest{FeatureKey: "tokidesk.reminders.run", ModuleKey: "tokidesk", CompanyID: companyID})

11. Read the org

Six reads cover most approval, routing and sharing needs. The app's service account must be a member of the company for all but the first (step 10). The three directories are the source for a "share with" or "assign to" picker: people, positions and groups, each reduced to what a picker shows. A member marked isGuest, an external person the company shares objects with, is refused all of them with 403; share with a guest by granting to their subject or to member:<id>#mapped_user as with anyone else, and let your own page show the guest what was shared.

const companies = await kiban.meCompanies(userBearer);                 // what this user may see
const people    = await kiban.memberDirectory(companyId, "ali");       // active members, kind person|service
const positions = await kiban.positionDirectory(companyId);            // id, code, title
const groups    = await kiban.groupDirectory(companyId);               // id, code, name (active)
const holder    = await kiban.positionHolder(companyId, positionId, "2026-10-01");
const members   = await kiban.groupMembers(companyId, groupId);
companies = kiban.me_companies(user_bearer)
people    = kiban.member_directory(company_id, q="ali")
positions = kiban.position_directory(company_id)
groups    = kiban.group_directory(company_id)
holder    = kiban.position_holder(company_id, position_id, "2026-10-01")   # KibanApiError 404: nobody that day
members   = kiban.group_members(company_id, group_id)
companies, err := kiban.MeCompanies(ctx, userBearer)
people, err    := kiban.MemberDirectory(ctx, companyID, "ali", 1, 25)
positions, err := kiban.PositionDirectory(ctx, companyID, 1, 25)
groups, err    := kiban.GroupDirectory(ctx, companyID, 1, 25)
holder, err    := kiban.PositionHolder(ctx, companyID, positionID, time.Now())
members, err   := kiban.GroupMembers(ctx, companyID, groupID)

To share with a person picked from the member directory, grant to the member, not to a subject: subjectType: "member", subjectId: <member id>, subjectRelation: "mapped_user". Kiban keeps the member-to-user link itself, so the share follows the person's current login and ends with the membership, and no subject lookup is needed.

For a page with many permission-driven controls, ask once: batchCan / batch_can / BatchCan take up to 100 object-relation pairs with the user's bearer and answer one decision each.

Where the user's token lives

Two shapes work with Kiban as shipped; the choice is the app's, not a Kiban setting.

  • The browser holds the token. The frontend track below: the browser SDK logs the user in, keeps the token in session storage, and the browser calls Kiban and your app with it. Simple, and it fits any static frontend. A script that manages to run in the page could read the token, so a strict content security policy matters.
  • Your backend holds the token. The user logs in, your backend receives the token and keeps it server-side, and gives the browser its own httpOnly cookie for the session, the shape an app with an existing cookie session already has. The browser never sees a Kiban token; your backend calls Kiban with the SDK and the token it holds, and your existing CSRF protection stays as it is. Add your backend's origin (for example https://app.example.com) to KIBAN_EXTRA_ORIGINS; every path under it, your callback included, is then a valid redirect URI. Exchange the code there.

Frontend track

Every TypeScript snippet on this page is compiled and run against the SDK by its test suite, so it works against the package as shipped.

1. Register your application's origin

Keycloak only completes a login whose redirect_uri is registered on the kiban-frontend client. Bootstrap writes that list on every start of the stack:

  • With KIBAN_DOMAIN unset (the default for make dev and the image quickstart), the list is fixed: http://localhost:3000/*, http://localhost:5173/*, http://localhost/*, https://127.0.0.1:8443/* and the test stack's https://127.0.0.1:18543/*. A development server on http://localhost:5173 or http://localhost:3000 works without any change.
  • With KIBAN_DOMAIN=app.example.com (the make public-up path sets it from KIBAN_PUBLIC_HOST), the list becomes exactly https://app.example.com/* and nothing else. Your application must be served from that origin, or behind the same reverse proxy as the gateway.

For any other origin, add it to KIBAN_EXTRA_ORIGINS in .env (comma-separated) and restart the stack: a web origin such as https://app.example.com is allowed to complete the login and joins the gateway's CORS allow-list; a custom scheme such as com.example.app:/callback is a native app's redirect URI. Bootstrap reconciles the client's lists to KIBAN_DOMAIN plus this variable on every start, so an edit in the Keycloak admin console lasts only until the next start; the variable is the place.

You should see: after the change, a login started from your origin lands back on your callback route instead of Keycloak's "Invalid parameter: redirect_uri" page.

2. Install the SDK

The package is on the public npm registry; no .npmrc and no token.

npm i @rossbsol/kiban-sdk

You should see @rossbsol/kiban-sdk in package.json. The package is ESM only and has no runtime dependencies; it needs fetch and crypto.subtle, which every current browser has.

3. Create the session

One session object per application, created once at startup. authOrigin is the gateway; the SDK never talks to Keycloak directly.

import { createSession } from "@rossbsol/kiban-sdk";

const gatewayOrigin = "https://127.0.0.1:8443";

const session = createSession({
  authOrigin: gatewayOrigin,
  realm: "kiban",
  clientId: "kiban-frontend",
  redirectUri: "http://localhost:5173/callback.html",
  persistTokens: true
});

persistTokens: true writes the token set to sessionStorage under kiban.oidc.tokens so a reload keeps the session; the entry goes away when the tab closes. Leave it off to keep tokens in memory only.

You should see nothing yet: session.isAuthenticated() is false until step 4 completes.

4. Gate a route on login and finish the login

A protected route asks the session first. When the user is signed out the SDK records a PKCE transaction and sends the browser to Keycloak; the function returns false so the route renders nothing.

export async function requireLogin(session: Session): Promise<boolean> {
  if (session.isAuthenticated()) return true;
  await session.login();
  return false;
}

The callback route (redirectUri above) exchanges the code once on load. The call is idempotent for the same code, so a React StrictMode double effect does not exchange it twice.

export async function finishLogin(session: Session, callbackUrl: string): Promise<void> {
  await session.handleCallback(callbackUrl);
}

Call it as finishLogin(session, window.location.href), then navigate to your application's home.

You should see: the browser goes to https://127.0.0.1:8443/auth/realms/kiban/protocol/openid-connect/auth?...code_challenge_method=S256, shows the Keycloak login page, and returns to your callback route with code and state in the query. After finishLogin, session.isAuthenticated() is true. On a make dev stack the first login as the superadmin also forces a password change.

5. Build the API client

Every request goes through one client that attaches the bearer and a correlation id, unwraps the { data } envelope and turns { error } into a KibanApiError.

import { createApiClient } from "@rossbsol/kiban-sdk";

const api = createApiClient({
  baseUrl: gatewayOrigin,
  getAccessToken: () => session.getAccessToken(),
  getAccessTokenExpiresAt: () => session.getTokens()?.expiresAt,
  refreshAccessToken: () => session.refresh()
});

You should see: await createOrgClient(api).meCompanies() returns the companies the user is an active member of. For a freshly bootstrapped stack that is [] even for the superadmin: nobody is a member of anything until a company and a member exist (see Administration).

6. Ask before showing a feature

canI answers "may this user use this feature, in this company?". A denial is a normal { allowed: false, reason }, never an exception. moduleKey is optional: when omitted it is taken from the feature key's first segment, and the decision always checks that this module is enabled.

export async function canSeeInbox(api: ApiClient, companyId: string): Promise<boolean> {
  const canI = createCanI(createEffectiveAccessClient(api));
  const inbox = await canI({ featureKey: "notification.inbox.view", moduleKey: "notification", companyId });
  return inbox.allowed;
}

You should see true for an active member of companyId when the notification module is enabled, and false with a reason such as COMPANY_MEMBERSHIP_REQUIRED otherwise. The request on the wire is POST /api/auth/effective-access/can with { "featureKey": "notification.inbox.view", "moduleKey": "notification", "scope": "company", "companyId": "..." }. Kiban answers for the bearer only: a body actorId naming anyone else is a 400 BAD_REQUEST, and no other subject field exists.

7. Call a module endpoint

The SDK has no typed client for the sample modules. api.request takes the path from the module's OpenAPI file, and the gateway forwards it to the module unchanged. Paths follow /api/<module>/v1/....

export interface NotificationChannel {
  id: string;
  companyId: string;
  key: string;
  label: string;
  kind: "in_app" | "email" | "webhook";
  target: string | null;
  createdAt: string;
}

export async function listChannels(api: ApiClient, companyId: string): Promise<NotificationChannel[]> {
  const page = await api.request<Page<NotificationChannel>>(`/api/notification/v1/companies/${companyId}/channels`, {
    query: { page: 1, pageSize: 50 }
  });
  return page.items;
}

You should see an array (empty on a new stack). A 403 with code MODULE_DISABLED or MODULE_NOT_INSTALLED means the module is off for this deployment; AUTHORIZATION_DENIED means the module's own check (notification.inbox.view here) refused the bearer. The types come from the module's API reference.

8. Handle 401 and refresh

The API client already does the common case: on a 401 it calls session.refresh() once (concurrent callers share one refresh) and retries the request once. A second 401 is thrown as a KibanApiError, so a rejected endpoint never loops. What is left for you is the branch on the error code:

try {
  await createOrgClient(api).adminCreateGroup(companyId, { code: "sales", name: "Sales" });
} catch (err) {
  if (!(err instanceof KibanApiError)) throw err;
  switch (err.code) {
    case ApiErrorCode.AuthTokenMissing:
    case ApiErrorCode.AuthTokenInvalid:
      void session.login(); // refresh already failed; start over
      break;
    case ApiErrorCode.Forbidden:
    case ApiErrorCode.AuthorizationDenied:
      // the caller may not do this; hide the control
      break;
    case ApiErrorCode.ModuleDisabled:
    case ApiErrorCode.ModuleNotInstalled:
      // the module is off for this deployment
      break;
    case ApiErrorCode.PositionHeld:
      // someone holds the position: call adminHandoverPosition with err.details.assignmentId
      // as expectedAssignmentId, which ends it and assigns in one step
      break;
    case ApiErrorCode.ValidationError: // org and the platform routes
    case ApiErrorCode.ValidationFailed: // the authorization service
    case ApiErrorCode.Conflict:
      // show err.message and err.details to the user
      break;
    case ApiErrorCode.AuthorizationUnavailable:
      // authz could not answer (503); retry later, never fail open
      break;
    default:
      throw err;
  }
}

You should see: an access token lives 300 seconds and the refresh token 30 minutes idle, 10 hours in total (the realm's defaults). Within those limits the user never sees a login page again; past them the AuthTokenInvalid branch starts a new login.

9. Log out

export function signOut(session: Session): void {
  session.logout();
}

You should see: the tokens are cleared, the browser goes to Keycloak's logout endpoint with the ID token as id_token_hint, and comes back to the origin root of redirectUri (http://localhost:5173/), not to the callback route. Pass postLogoutRedirectUri to createSession for a different landing page; it must be registered on the client too.

For the full API and the recipes, see the SDK guide.

Administration

A superadmin creates companies and org units through the gateway, with the token from Getting a token for the shell. Members, positions, assignments and groups of a company are managed by the superadmin or by an administrator of that company: a member who holds the company's admin relation (company:<id>#admin, granted with POST /api/auth/grants by a superadmin). The sample shell's administration pages use the same routes for positions and groups.

Create the company. A company has no parent; typeKey is company:

curl -sk https://127.0.0.1:8443/api/org/admin/units \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"typeKey":"company","parentId":null,"code":"acme","name":"Acme Ltd"}'
{ "data": { "id": "<companyId>", "typeKey": "company", "parentId": null, "code": "ACME", "name": "Acme Ltd", "isActive": true } }

Creating an active company also links every enabled app and module to the platform for that company in the same transaction (company_module:<companyId>/<key>#system), so superadmins administer it from the start. An org unit below the company is the same call with "typeKey": "business_unit" or "territory" (the shipped taxonomy) and "parentId": "<companyId>". Codes are normalised to upper case.

Create a member and link it to a login. kcSub is the sub claim of the user's token; the identity record exists as soon as that user has made one request through the gateway (a login followed by any API call):

curl -sk https://127.0.0.1:8443/api/org/admin/members \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"companyId":"<companyId>","code":"ross","displayName":"Ross Chiu","email":"ross@example.com"}'

curl -sk https://127.0.0.1:8443/api/org/admin/members/<memberId>/link-user \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"kcSub":"<sub>"}'

You should see the member with "userId" set after the link, and GET /api/org/me/companies as that user now lists the company. GET /api/org/admin/members?companyId= lists a company's members; PUT /api/org/admin/members/{id} updates one; DELETE .../link-user unlinks.

REST-only track

What you can and cannot do

  • Every call needs a bearer: a user's access token from a browser login, or a service client's token from the client-credentials grant (below). A backend acts either on behalf of the user whose token it holds or as itself.
  • Every response is an envelope: { "data": ... } on success, { "error": { "code", "message", "details"? } } on failure. Send x-correlation-id if you want to find the request in the gateway's logs and the audit rows; the gateway generates one otherwise.

Route families

All on the gateway origin. The full contract is the Platform API.

Family What it is Who may call it
POST /api/auth/effective-access/can, .../batch-can The access decision for the bearer, one or many objects (at most 100 per batch) Any bearer, for itself only
GET /api/auth/effective-access/summary?companyId= Feature keys, role bindings and object grants the bearer holds Any bearer, for itself only
POST /api/auth/grants Write or remove relation tuples, bound to one company and one app or module A registered app's backend, on its own object types; an app's backend that holds the company's admin relation, on any app's types there; or a superadmin (who also appoints a company administrator with it)
GET /api/org/companies/{id}/members/by-subject/{sub} Is this subject an active member, and which member A registered app's backend, or a superadmin
GET /api/org/me/companies Companies the bearer is an active member of Any bearer
GET /api/org/companies/{id}/members?q=&page=&pageSize= Member directory of one company Active members of that company, or a superadmin
/api/org/admin/units, /api/org/admin/units/{id}, .../subtree Company and org-unit administration Superadmin
/api/org/admin/members, /api/org/admin/members/{id}, .../link-user Member administration Superadmin, or an administrator of that company
/api/org/admin/companies/{id}/positions, .../groups, /api/org/admin/positions/{id}, /api/org/admin/positions/{id}/assignments, /api/org/admin/positions/{id}/handover, /api/org/admin/assignments/{id}/end, /api/org/admin/groups/{id}/members Position and group administration Superadmin, or an administrator of that company
POST /api/platform/admin/apps Register an app from its manifest Superadmin
GET /api/platform/capabilities[/{module}], GET /api/platform/catalog What is registered, installed and enabled Any bearer
POST /api/platform/admin/modules/{key}/enable, .../disable; POST /api/platform/admin/platform-roles, DELETE .../platform-roles/{role}/{subjectId} App and module enablement, the superadmin role Superadmin
/api/<module>/v1/... A built-in module's own API, forwarded unchanged Whatever the module decides

A minimal call:

curl -sk https://127.0.0.1:8443/api/auth/effective-access/can \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"featureKey":"tokidesk.ticket.view","moduleKey":"tokidesk","scope":"company","companyId":"'"$COMPANY"'"}'

You should see {"data":{"allowed":true,"reason":"ALLOWED","evidence":[...]}} for a member once the app is enabled and allowed: false with COMPANY_MEMBERSHIP_REQUIRED for someone who is not a member. Kiban answers for the bearer: a body actorId naming anyone else is a 400 BAD_REQUEST.

Getting a token for the shell

Because there is no direct grant for users, take the token from a browser session. Log in to the sample shell (https://127.0.0.1:8443), open the browser's developer tools and run:

JSON.parse(sessionStorage.getItem("kiban.oidc.tokens")).accessToken

The shell persists its tokens under that key. Export the value as TOKEN. It is valid for 300 seconds; take a fresh one when you get 401 AUTH_TOKEN_INVALID. Its sub is your subject.

Getting a token for a service

curl -sk https://127.0.0.1:8443/realms/kiban/protocol/openid-connect/token \
  -d grant_type=client_credentials -d client_id=tokidesk-backend -d client_secret=$SECRET

You should see a JSON body with access_token, valid for 300 seconds. Its sub is the client's service-account user and its azp is the client id, which is how the gateway and the authorization service recognise the app's backend. The SDKs do this for you.

Next