Appearance
Minting SDK tokens — your backend
§ 5.1 is the app side. This is the other half: the one endpoint your server implements, and the rules that come with it. Written for whoever runs that server, who may not be the person integrating the app.
Why this lives on your server
Your SDK Key (sbsk_…) is one long-lived credential for your whole organization, identical for every one of your users. Anyone holding it can create or sign into accounts in your organization — for any user id they can obtain, and user ids are not secret (your own support staff see them in the dashboard, as does anyone who has ever had that access).
So the key must never be somewhere an attacker can reach it, and "inside your mobile app" is somewhere an attacker can always reach it: a shipped binary is not a secret, whether the key is compiled in or fetched from an endpoint of yours at runtime.
The exchange makes possession of a key insufficient. Your backend keeps the key, authenticates your own user, and mints a token worth exactly one sign-in for one user for a few minutes.
| Credential | Who holds it | Lifetime | Worth if leaked |
|---|---|---|---|
SDK Key (sbsk_…) | your backend, only | until you revoke it | the ability to mint tokens; revocable, and revoking it signs out live sessions |
SDK token (sbst_…) | your app, briefly | 5 min default, single use | one register-or-login, one user, inside that window |
| Access token | your app | 15 min | that one user's data until it expires |
| Refresh token | your app | 60 days of inactivity | that one user's session until sign-out or key revocation |
Nothing the app holds is organization-wide.
The contract you serve to your app
Your app needs two values from you. Everything else is your choice — path, auth, shape:
json
{
"sdk_token": "sbst_…",
"organization_id": "3f7c1a20-9b4e-4c11-a0d2-71f0c9a8e512"
}A workable default is POST /sdk/token on your existing API, authenticated the way the rest of your API is (session cookie, bearer token, whatever you already use). It takes no request body: the user is whoever your own authentication says they are.
The call you make to Sensor Bio
The request and response are the ones shown in §5.1. The request body is optional and every field in it is optional too — an empty object, or no body at all, is the common case:
| Field | Required | Notes |
|---|---|---|
expires_in_seconds | no | 30 to 1800. Omit for the 5-minute default. |
sdk_key_id | no | Which of your SDK Keys the token is anchored to. Only meaningful on the APIKey path below. |
The response carries Cache-Control: no-store. The raw token is shown exactly once — only a hash of it is stored on our side, so there is no way to look it up again.
Authentication. Send exactly one of:
Authorization: SDKKey sbsk_…— your SDK Key. The key you present is itself the anchor, so nothing is ambiguous. Preferred.Authorization: APIKey sbak_…— your organization API Key, offered so a backend that already holds one need not also deploy an SDK Key. The anchor is then resolved from your usable SDK Keys, and you must passsdk_key_idif you have more than one.
Protocol. The API requires HTTP/2. Every modern HTTP client uses it automatically over TLS. If you get an HTTP 464, something in your stack forced HTTP/1.x — check for an explicit version flag, a proxy, or a load balancer in front of your egress.
Verify your key before writing any code:
bash
curl -sS -X POST https://staging.api.sensorbio.com/sdk/v1/token \
-H "Authorization: SDKKey $SENSORBIO_SDK_KEY" \
-H 'Content-Type: application/json' \
-d '{}'A token back means your credential works and the exchange is reachable. That separates "my key is wrong" from "my integration is wrong", which is worth knowing before you debug anything else.
Four rules that actually bite
Authenticate your own user first. This endpoint cannot do it for you, and the token it returns is enough to create an account in your organization. Mint only after your own authentication has succeeded, and only for the user it succeeded for. An endpoint of yours that mints for any caller is the leak you just eliminated, wearing a different hat.
One token per sign-in. Never cache one. Tokens are single-use. A cache hands an already-spent token to the next caller, and the failure surfaces as an authentication error inside registerUser — far from the cache that caused it. Mint fresh every time, including every time the SDK asks again.
Don't put the user id in the request. Sensor Bio does not need to know your user. The token is anchored to your organization; your app tells the SDK which of your users it is registering.
Prefer a random, opaque user id. The identifier your app hands the SDK (client_sdk_user_id) is yours to choose. Generate a random one per user and keep the mapping on your side, and Sensor Bio never holds an identifier that means anything in your systems. Whatever you choose must be stable for that user — the first register for an id creates the account, and every later call with the same id signs the same person back in.
Errors
The error body is {"status": …, "title": …, "detail": …}.
| Status | Meaning | What to do |
|---|---|---|
401 | The credential was rejected. Unknown, revoked and expired keys answer identically, by design. | Check all three: the whole key was copied, it has not been revoked, it has not expired. |
403 | Your organization has no usable SDK Key. | Create one under Developer Settings. |
400 | An out-of-range expires_in_seconds, or an sdk_key_id that is unknown or was required and omitted. | Fix the parameter. expires_in_seconds must be 30–1800. |
464 | The request arrived over HTTP/1.x. | Enable HTTP/2 (see above). |
5xx | Our problem, almost certainly not your credential. | Retry; if it persists, contact developers@sensorbio.com. |
Surface the upstream status to your app rather than collapsing everything into "token error" — a 401 from us and a failure of your own user authentication want different handling, and only your backend can tell them apart.
Reference implementations
Both do the same three things: authenticate your user, exchange, return two fields.
Node (Express):
js
app.post("/sdk/token", requireYourAuth, async (req, res) => {
const upstream = await fetch("https://api.sensorbio.com/sdk/v1/token", {
method: "POST",
headers: {
Authorization: `SDKKey ${process.env.SENSORBIO_SDK_KEY}`,
"Content-Type": "application/json",
},
body: "{}",
});
if (!upstream.ok) {
const detail = await upstream.text();
return res.status(502).json({ error: "sdk_token_exchange_failed", upstream_status: upstream.status, detail });
}
const { sdk_token, organization_id } = await upstream.json();
res.set("Cache-Control", "no-store").json({ sdk_token, organization_id });
});Go:
go
func mintSDKToken(ctx context.Context, sdkKey string) (token, orgID string, err error) {
req, _ := http.NewRequestWithContext(ctx, http.MethodPost,
"https://api.sensorbio.com/sdk/v1/token", strings.NewReader("{}"))
req.Header.Set("Authorization", "SDKKey "+sdkKey)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", "", err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
body, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<10))
return "", "", fmt.Errorf("exchange failed (HTTP %d): %s", resp.StatusCode, body)
}
var out struct {
SDKToken string `json:"sdk_token"`
OrganizationID string `json:"organization_id"`
}
if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
return "", "", err
}
return out.SDKToken, out.OrganizationID, nil
}Keep the key in your secret manager or environment, never in source control, and never log it. Log tokens by prefix only (sbst_ABCD…) if at all — we store that same prefix, so it is the half worth quoting in a support request.
Choosing a lifetime
The default 300 seconds is generous, because the token should be minted at the moment it is used: your app asks, you mint, it registers, the token is spent. Seconds, not minutes.
Longer lifetimes only widen the window in which a token intercepted in transit is still worth something. Mint on demand and leave the default alone; reach for expires_in_seconds mainly when testing what your app does with an expired token.
Revoking and rotating keys
Revoking an SDK Key in the dashboard signs out every user currently signed in through it, immediately and on every device, as well as preventing new sign-ins. Accounts and data are untouched, and people sign back in as soon as your backend is minting with a working key. That makes revocation your mass-logout lever for a suspected compromise, and it makes an unplanned revocation disruptive.
To rotate without signing everyone out at once, do it in this order:
- Create the new SDK Key.
- Switch your backend to it and confirm tokens mint.
- Only then revoke the old one — the sessions anchored to it end at that moment.
Multiple keys are also how you separate environments: a "staging app" key and a "production app" key can be revoked independently.
Evaluating before you have a backend
The example app in this repository does the exchange in-process, mocking the backend described here so the SDK can be run end to end without one. It is marked as a stand-in everywhere it appears — in SdkTokenExchange.kt, in the example app's README, and on the register screen itself — because it does the one thing this section exists to prevent: it holds an SDK Key on a device.
Read it as a worked example of the request, the response, and what the app does with the result. Do not copy it into an app you ship. If you would rather run the stand-in outside your app while you integrate, ask developers@sensorbio.com — a throwaway local server that serves exactly the contract above is available.
Checklist
- [ ] SDK Key lives in your secret manager, is not in source control, and is never logged.
- [ ] Your minting endpoint requires your own authentication and mints only for that user.
- [ ] Nothing caches, stores, or reuses a token.
- [ ] Your app receives only
sdk_token+organization_id. - [ ] The upstream status reaches your app in a form it can act on.
- [ ]
client_sdk_user_idis stable per user, and ideally random and opaque. - [ ] Rotation is create → switch → revoke, and you know revocation signs out live sessions.