Docs Credentials

Credentials

The kinds of credential and who holds each, how API keys are made and revoked, and an app's rules.

Documentation

Every request carries Authorization: Bearer <credential>. There are five kinds:

Credential Who holds it What it is
API key (bga_…) your server The app's own server: everything within the app. With the header X-Bonga-User: <user id> it acts as that user. Limited for the whole app, far above a person: see limits.
User token your front end A JWT issued by POST /api/v1/tokens. The user it was issued for, until it expires (24 hours unless asked otherwise, 7 days at most) or the user is signed out everywhere (DELETE /api/v1/users/{id}/tokens).
Identity provider's token your front end An access token of an OpenID Connect provider the app trusts, with the header X-Bonga-App: <app key>. See below.
Platform key the operator Opens /api/v1/platform/** and the actuator: creating apps, their API keys, their rules. Nothing inside an app. 32 characters or more: the server does not start with a shorter one.
Dashboard sign-in a person, in the dashboard An access token of the dashboard's authorization server. Opens /api/v1/dashboard/** and nothing else: see the dashboard.

An API key is shown once, when it is created; only its hash is kept. Whatever goes wrong at the door, the caller learns no more than that it was not let in (401).

Apps and keys

A key that is revoked, or reaches its expiresAt, stops working at once on every node, and the WebSocket connections opened with it are closed with 4401 within seconds.

Signing up through the dashboard

The dashboard at /dashboard/ gives out keys without the platform key. A person signs in at FoxShard Identity (identity.foxshard.com), or signs up there first, and back on the page signs an app up: its key, its name, what it is. Its rules are the defaults below, and its first API key is shown once. They see their apps and keys afterwards, make more keys for an app, five that work at most, and revoke them: a key that leaked, or the old one of a rotation, stops working at once, on every node. One person may sign up three apps.

Whoever signed an app up also changes its rules there (Rules, on the app): its name and what it is, whether its users may start direct conversations, create groups and search all users of the app, and how long a message may be edited. What is saved is in effect at once. The page shows the plan each app is on and how much it holds of what the plan allows (plans); the plan itself, and how large an app's groups, messages and files may be, are the operator's to set.

An admin (the role ADMIN of the application bonga at the authorization server) sees every key of every app, with whoever signed the app up, and revokes any of them. Apps made with the platform key are there too, with no owner.

An app's rules are set when it is created, and changed later: by the operator with PATCH /api/v1/platform/apps/{key}, and by whoever signed the app up in the dashboard, for the first three and editWindowSeconds. An app made in the dashboard starts with the defaults:

Rule Default Meaning
allowClientDirect true users may start a direct conversation with any user of the app
allowClientGroups true users may create groups
allowUserDirectory false users may search and look up all users of the app, not only those they share a conversation with
maxGroupMembers 500
maxMessageLength 10000 characters
maxFileBytes 26214400 25 MB; 0 switches uploads off
editWindowSeconds none how long a sender may edit a message
status ACTIVE SUSPENDED turns the whole app away at once: keys, tokens and open connections
plan FREE how much the app may hold, FREE or PLUS (plans)

With both switches off, only your server starts conversations: right for an application where who may talk to whom is its own business (a customer and their rider, a buyer and a seller).

Users who already sign in somewhere

If your users have access tokens of an OpenID Connect provider, register it and no token of Bonga's is needed:

curl -s -X PUT $API/platform/apps/duka/issuers -H "Authorization: Bearer $PLATFORM_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"issuerUri":"https://id.example.com","audience":"duka-chat"}'

The front end then calls with Authorization: Bearer <access token> and X-Bonga-App: duka. The token is checked for its signature (against the provider's published keys, asymmetric algorithms only), its issuer, its audience and its times. The audience is required: a provider issues tokens to other applications too, which are not to sign anybody in here. The user is created on first sight from the claims sub, name and picture; userIdClaim, nameClaim and avatarClaim name others, and jwkSetUri says where the keys are when the provider has no discovery document. The provider's keys are fetched again when a token names one that is not known, at most every 30 seconds, whatever tokens come in.

Whose users are whose. Without a userIdPrefix, the id in the token is the user's id here: right for a provider whose ids are the ones your server knows its users by, as when the provider is your own sign-in. A provider whose users are other people, or a second provider, needs a prefix of its own, e.g. "userIdPrefix":"google:": its user 123 is then google:123 here, and never the user 123 your server makes tokens for, nor anybody of another provider. A prefix is letters, digits and ._-, with a colon at the end; no two providers of an app share one, and at most one active provider has none. A provider registered before these rules, without an audience, or next to another one without a prefix, has its tokens refused, and the log says why, until it is registered again.

An app made in the dashboard starts with the default rules above, and whoever signed it up changes them there, under Rules. To register an identity provider for your app, write to support@foxshard.com.