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.