Restricted tokens
A restricted token is an access token carrying a restrictedTo object. The gateway checks it on every call and refuses the token anywhere outside the scope it names. Restricted tokens have no refresh token.
The typical use is pairing: a user already signed in on a mobile app authorizes a web app that belongs to a different tenant and product, without signing in again. The mobile app scans a QR code (or follows a deep link), a service you write mints a token scoped to the web app, and the web app uses it.
Requirements
Section titled “Requirements”| Package | Minimum version |
|---|---|
soajs.core.modules |
5.2.21 |
soajs |
4.1.23 |
soajs.controller |
4.3.16 |
soajs.oauth |
3.1.24 |
Pairing flow
Section titled “Pairing flow”Web app (tenant B) Your pairing service Mobile app (tenant A, signed in) │ POST /pairing (tenant B key, │ │ │ deviceId + agent of the browser) │ │ │──────────────────────────────────► │ store scope = tenant B │ │ ◄──────────── pairingId ────────── │ + product of the key │ │ show QR / deep link with pairingId│ │ │ │ ◄── POST /pairing/:id/authorize │ │ (tenant A key, user's access_token, │ │ device-id of the phone) │ │── POST /restricted/token/auto/:userId ──► oauth │ │◄──────────── access_token ─────────────── │ GET /pairing/:id (polling) │ │ │──────────────────────────────────► │ │ │ ◄──────── access_token (once) ──── │ │ │ │ API calls: tenant B key + access_token + device-id of the browser ▼ gateway: token not expired, deviceId matches, restrictedTo matches the keyYour pairing service is a normal multi-tenant SOAJS service. The two halves of a pairing arrive under different tenants (the web app’s key, then the mobile app’s key), so the pairing store must be shared, not per tenant.
- At
POST /pairing, the caller is the web app:req.soajs.tenant.idandreq.soajs.tenant.application.productare the scope the token should be restricted to. Store them on the pairing, with the browser’s device id and user-agent from the request body. - At authorize, take the user id from
req.soajs.urac._id(the gateway authenticated the mobile token), never from the request body. - Grant the two public routes (open and poll) in the web app tenant’s package ACL, and the authorize route as a private API in the mobile app’s package.
Mint API
Section titled “Mint API”POST /restricted/token/auto/:idAPI group Internal in soajs.oauth. Call it from your service over interConnect, not through the gateway:
// config.js of your service"interConnect": [{ "name": "oauth" }]req.soajs.awareness.connect("oauth", (peer) => { // POST http://${peer.host}/restricted/token/auto/${req.soajs.urac._id} // forward peer.headers as-is: they carry soajsinjectobj, so oauth sees // the same tenant and user as your route});Without the interConnect entry, awareness.connect returns the gateway host instead, and the call takes a different path.
Parameters
Section titled “Parameters”| Field | In | Required | Description |
|---|---|---|---|
id |
path | yes | URAC user id. |
restrictedTo |
body | yes | Where the token may be used. Unknown keys are rejected. |
deviceId |
body | no | The web app’s device id. Omit it and the token is not device-bound. |
agent |
body | no | The web app’s user-agent. Only enforced if restrictedTo.agent is also set. |
ttl |
body | no | Lifetime in seconds, minimum 60. Defaults to accessTokenLifetime (7200). |
loginMode |
body | no | oauth (default) or urac. See Login mode. From soajs.oauth 3.1.31. |
deviceId and agent are body fields because on this call the device-id and user-agent headers belong to your service, not to the browser. Pass the values stored when the pairing was opened.
restrictedTo
Section titled “restrictedTo”Each key takes a string or an array of strings. Only the keys present are checked, on every call.
| Key | Required | Checked against |
|---|---|---|
tenant |
yes | the tenant of the external key on the request |
product |
no | the product of that key’s application |
package |
no | the package of that key’s application |
key |
no | the external key itself |
env |
no | the gateway environment (SOAJS_ENV), case-insensitive |
agent |
no | the user-agent header, exact match |
{ "restrictedTo": { "tenant": "<web-app-tenant-id>", "product": "<web-app-product-code>" }, "deviceId": "<browser-device-id>", "agent": "<browser-user-agent>", "ttl": 3600}Response:
{ "result": true, "data": { "token_type": "bearer", "access_token": "<access-token>", "expires_in": 3600 }}Login mode
Section titled “Login mode”By default the minted token has loginMode oauth: the gateway takes the user straight from the token and does not look it up in the web app’s tenant. The user’s status and groups stay as they were at mint time until the token expires. This is what the pairing flow needs.
With loginMode urac, the gateway loads the user from URAC on every call, like an ordinary session:
- a user set to inactive is refused (error 146) on the next call;
- group changes apply on the next call.
Use it only when the token is used under a tenant the user belongs to, since the lookup is made in the tenant of the request. Under another tenant, every call is refused. The gateway’s getUserFromToken setting must be off, or the user is taken from the token again.
From soajs.oauth 3.1.32, when restrictedTo.tenant names one tenant, a urac mint finds the user under that tenant instead of the calling one. The user must have it as home tenant or be invited to it. This lets a service mint for users of other tenants, for example AI agents that are users of a customer’s tenant.
Mint errors
Section titled “Mint errors”| Code | Meaning |
|---|---|
| 400 | Required data missing. |
| 413 | User not found for :id in the calling tenant, or, with loginMode urac, in the one tenant restrictedTo.tenant names. |
| 415 | The call carries a user’s own token and :id is a different user. |
| 416 | The user record is missing a required field (username, tenant, …). |
| 600 | Token generation failed. |
Using the token
Section titled “Using the token”Every call from the web app sends:
| Header | Value |
|---|---|
key |
The web app’s external key. Its tenant, product, package and key are matched against restrictedTo. |
access_token |
The restricted token. |
device-id |
The same device id that was passed at mint. |
user-agent |
Sent by the browser. Only checked when restrictedTo.agent is set. |
Use the access_token header (or query parameter). Do not rely on Authorization: Bearer for restricted tokens: the gateway only normalizes the access_token header and query parameter, so a bearer header is not inspected on public APIs.
What the gateway enforces
Section titled “What the gateway enforces”On every private call:
- the token exists and is not expired;
user.deviceIdon the token matches thedevice-idheader, otherwise error156;- every key in
restrictedTomatches the request, otherwise error147(Token restriction mismatch); - a restricted token reaching a service with
extKeyRequired: falseis refused with147, since there is no key to compare against.
There is no registry switch for the restriction check: it is always on for tokens that carry restrictedTo, and tokens without it are unaffected.
When the token stops working (147, 156, or expiry), the client should start a new pairing, not retry. There is no refresh token.
Revoking
Section titled “Revoking”DELETE /restricted/tokens/user/:userIdDeletes all restricted tokens of the user and leaves their other sessions in place. Returns the number deleted. To end a single browser session, keep the token and call DELETE /accessToken/:token.
Guest tokens
Section titled “Guest tokens”POST /restricted/token/guestAlso group Internal. Mints a restricted token for an identity that has no URAC record: username and tenant ({ "id", "code" }) are required, restrictedTo, deviceId, agent and ttl work as above, and an optional claims object is copied onto the token’s user. claims may not contain _id, id, username, tenant, loginMode, guest, restrictedTo, deviceId or agent (error 417). The id is generated by the service. Anything that can reach this route can mint a token for any identity, so never grant it in a package ACL.
Checklist
Section titled “Checklist”- Add
device-idtoserviceConfig.cors.headersin the environment registry, otherwise the browser preflight fails before the call reaches the gateway. - Add
interConnect: [{ "name": "oauth" }]to the pairing service. - Make
pairingIdunguessable (CSPRNG, for example 32 random bytes), short-lived, single use, and bind the poll to thedevice-idthat opened it. - Rate limit the public poll route.
- Set
restrictedTo.tenantto the web app’s tenant, not the tenant of the authorize call. - If APIs on the web app’s product restrict access to groups, use the group codes of the user’s own tenant; the token carries those groups (otherwise
160). - Keep
ttlshort when you setrestrictedTo.agent: browser user-agents change on update and the match is exact.
