Companion apps
Last updated 2026-11-15
A companion app is your own app — on iOS, Android, desktop or the web — that talks to a user's
box as a registered OAuth client. Nothing of yours is installed on the box, except the service
.plu you may also ship alongside it.
An app that only wants the box as storage, with no box-side code at all, is listed in the store as
a compatible app: same registration, same scopes, no .plu.
Every app needs an icon. Register a compatible app with one (Register a compatible app in
the console: a square PNG, 512 × 512 recommended, 256–2048 px, up to 1 MB); an installable app
gets it from its upload. Boxes show it on the consent screen, in the store, and next to your app's
folder (/Apps/<app name>) and its connections in the owner's Drive and settings. A client has no
icon of its own: every client of the app shows the app's icon. An app registered before icons were
required can't add clients until it has one — add it on the app's Settings tab.
1. Register the client
A client id is <app_id>:<label>, where the app id is yours and the label is
[a-z0-9-]{1,32} — e.g. dev.jan.notes:ios. Register it in the console under Clients on the
app page, or declare it in your manifest's clients[] and let the store pick it
up on upload. A box refuses an unregistered client id outright: no registration, no consent screen.
Redirect URI rules, enforced on registration and again at authorization:
- a custom scheme —
notes://auth/callback; - http loopback —
127.0.0.1,::1orlocalhost, and the box matches any port, so you do not have to register the ephemeral one (RFC 8252 §7.3); httpsis refused — by the box when it validates the request, and by the store for any client declared in a manifest. (The store has an admin-onlyallow_https_redirectsflag, off by default, for future universal-link support; the shipped box does not honour https redirects either way, so do not build on it.)
Everything else must match the registered string exactly.
2. Scopes
The manifest permission words, plus one scope that exists only for OAuth clients (files:app):
| Scope | Grants |
|---|---|
files:read |
read the user's files — the whole Drive |
files:write |
change them (implies read) |
files:app |
read and write only the app's own folder, /Apps/<app display name> |
user:profile |
the signed-in user's profile |
service:call:<app_id> |
call that app's service at /apps/<app_id>/svc/* |
read and write are accepted aliases (write expands to files:read files:write). admin is
not delegatable — a box rejects it in an OAuth request. A request may only ask for scopes
inside the client's registered scopes_allowed, and service:call: may only name your own app.
files:app — the app's own folder
A backup or sync app rarely needs the user's whole Drive; it needs somewhere to keep its own
files. Ask for files:app instead of files:read + files:write: it is the smaller thing
for the user to agree to.
When the box issues the token it creates the folder /Apps/<app display name> and returns its
path as app_folder in the token reply (below). Paths you send stay absolute Drive paths inside
it — /Apps/Notes Backup/2026/notes.md. A files:app token reaches these routes, and only for
paths inside that folder — every path a request names must be inside it:
| Routes | |
|---|---|
| Read | /api/drive/list, /api/drive/download, /api/drive/view, /api/drive/archive, /api/drive/versions, /api/drive/version-content |
| Write | /api/drive/upload, /api/drive/mkdir, /api/drive/rename, /api/drive/move, /api/drive/save-text, /api/drive/save-copy, /api/drive/restore-version, /api/drive/delete, chunked uploads /api/uploads/* |
Any other route, or a path outside the folder, is 403.
- It is a scope of its own: it neither implies nor is implied by
files:read/files:write. Those two still reach the whole Drive, so a client that also asks for them is no longer folder-only — leave them off if the folder is all you need. - It is an OAuth-client scope only. A
.plucannot declare it in its manifestpermissions.
Older boxes refuse the whole client. A box on core 1.11.3 or older does not know
files:app, and a box that finds a scope it does not know in a client's scopes_allowed refuses
that client entirely — it fails closed, so the scopes it does know stop working for that client
too. Add files:app to an existing client only when the boxes you target have updated; until
then, register a separate client for it (e.g. dev.jan.notes:ios-folder) and leave the old one
as it is.
3. The authorization flow
Authorization Code with PKCE (S256 — the box accepts no other method), and refresh tokens to keep the connection going once the user has approved.
- Build a verifier (43–128 characters), a challenge
base64url(SHA-256(verifier))and a randomstate. - Send the user to the portal, which finds their box and hands the request to it:
https://plumbox.me/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&code_challenge=…&code_challenge_method=S256&state=…. The box renders the consent screen at its ownGET /authorizeusing the registered display name and icon — anything you pass in the query is ignored. A signed-out or stale session is bounced back to the portal to log in; an API-token session may not approve an app at all. - The user approves; the box redirects to your
redirect_uriwithcode,stateandiss(the box's own address). Codes are one-time and live 5 minutes. - Exchange the code at the box, not the portal:
POST https://<box>/api/oauth/token
Content-Type: application/json
{"grant_type":"authorization_code","code":"…","code_verifier":"…",
"client_id":"dev.jan.notes:ios","redirect_uri":"notes://auth/callback"}
The body may also be form-encoded (application/x-www-form-urlencoded, as RFC 6749 has it) with
the same fields.
{"access_token":"plum_pat_…","token_type":"bearer","expires_in":3600,
"refresh_token":"plum_rt_…","scope":"files:app user:profile",
"app_folder":"/Apps/Notes Backup"}
The access token carries what the user approved and expires after an hour (expires_in, in
seconds). app_folder is there only when files:app was granted. Store all of it — access
token, refresh token, app_folder and the box's address — in the platform keystore. The user can
disconnect the app at any time in the box's token settings.
A box on core 1.11.3 or older answers with access_token, token_type and scope only. That
token never expires and there is nothing to refresh; keep using it. Tokens issued before boxes
learned to expire them keep working the same way.
Errors come back as {"error":"…","error_description":"…"} with unauthorized_client,
invalid_scope, invalid_redirect_uri, invalid_grant, invalid_request,
unsupported_grant_type, recent_authentication_required, unauthorized (401),
temporarily_unavailable (503) or server_error.
Refreshing
Trade the refresh token for a new pair at the same endpoint:
POST https://<box>/api/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=plum_rt_…&client_id=dev.jan.notes%3Aios
The reply has the same shape as above: a new access token and a new refresh token.
- Refresh tokens rotate. Each refresh retires the refresh token you sent; save the new one before you do anything else. For 60 seconds the box still accepts the previous one, so a retry after a reply that got lost works. After that, presenting an old refresh token looks like a stolen copy: the box revokes the whole connection, and the user has to connect again.
- Run one refresh at a time per connection, and refresh shortly before
expires_inruns out or once when a request comes back 401. - A refresh token that goes 90 days unused expires.
400 {"error":"invalid_grant"}from a refresh means the connection is gone — rotated away, disconnected by the user, expired, or revoked after a reuse. Do not retry; send the user through the authorization flow again.503 {"error":"temporarily_unavailable"}(the box's Drive is not available, so it cannot recreate your app folder) can come after the box has already rotated the token. Retry with the same refresh token within 60 seconds — the grace window above. A retry after that is treated as reuse and ends the connection; if the box is still unavailable by then, wait and let the user reconnect.- A network failure with no reply at all is the same case: retry with the same token inside the 60 seconds.
GET /.well-known/oauth-authorization-server on the box lists
"grant_types_supported":["authorization_code","refresh_token"] (a box that does not refresh
lists authorization_code only).
Only tokens from this exchange expire. Personal access tokens the user creates by hand — in Settings, as a DAV Basic password, or a device credential — are unchanged and long-lived.
401 or 403
- 401 with
WWW-Authenticate: Bearer error="invalid_token": the access token expired or is no longer valid. Refresh once and send the request again; if the refresh saysinvalid_grant, reconnect. - 403: the credential is fine, the request is not allowed — a scope you were not granted, or
a path outside your
files:appfolder. Refreshing will not change that, and it is no reason to sign the user out.
4. Calling the box
import { PlumClient, beginAuthorization, exchangeCode, parseCallback } from "@plumbox/client";
const clientId = "dev.jan.notes:cli";
const redirectUri = "http://127.0.0.1:53682/callback";
const req = await beginAuthorization({
clientId, redirectUri,
scopes: ["files:app", "service:call:dev.jan.notes"],
});
open(req.url); // browser / Custom Tabs / ASWebAuthenticationSession
// …your redirect handler receives the callback URL…
const cb = parseCallback(callbackUrl); // refuses an iss that is not a Plum box
const tokens = await exchangeCode({
baseUrl: cb.iss, code: cb.code, state: cb.state, expectedState: req.state,
codeVerifier: req.codeVerifier, clientId, redirectUri,
});
await keystore.save(cb.iss, tokens); // accessToken, refreshToken, expiresAt, appFolder
const box = new PlumClient({
baseUrl: cb.iss, clientId,
token: tokens.accessToken,
refreshToken: tokens.refreshToken,
expiresAt: tokens.expiresAt,
appFolder: tokens.appFolder,
onTokens: (t) => keystore.save(cb.iss, t), // every refresh rotates the refresh token
onAuthError: () => askToReconnect(), // invalid_grant, or a 401 a refresh did not cure
});
const page = await box.drive.list(box.appFolder!); // GET /api/drive/list, inside /Apps/<name>
const ent = await box.apps.entitlement("dev.jan.notes"); // GET /api/apps/{id}/entitlement
@plumbox/client 0.4.0 keeps the access token fresh by itself when you give it the refresh
token and clientId: it refreshes shortly before expiry and once on a 401, then hands the new
token set to onTokens — persist it there, because the refresh token you stored before has just
been retired. refreshTokens(...) does the same by hand. Earlier versions do not refresh: with
them, a token from an updated box stops working after an hour. The package also has
drive.upload/download/mkdir/move/remove/trash/versions, auth.createToken/listTokens/
revokeToken/logout, and apps.status/ensureServiceInstalled/refreshEntitlements. It is ESM+CJS,
Node 18+, zero runtime dependencies. Install it with npm i @plumbox/client.
5. Native SDKs
The same client exists for native apps, with the same names and the same behaviour as
@plumbox/client: delegated OAuth with PKCE, the iss and state checks before anything is
sent, the hourly access token renewed by itself (shortly before expiry and once on a 401, one
refresh at a time), every rotated set handed to you to persist, invalid_grant reported once,
and the Drive (chunked uploads above 8 MiB). Each also opens the system browser for you and keeps
the tokens in the platform's secure store.
| Platform | Package | Browser | Token store |
|---|---|---|---|
| iOS 15+ / macOS 12+ | PlumBoxClient — Swift Package from https://github.com/plum-networks/plum-sdk |
PlumAuthorizationSession (ASWebAuthenticationSession) |
KeychainTokenStore |
| Android (minSdk 24) | im.plum:plumbox-client (Gradle) |
PlumAuthorization.launch (Custom Tabs) |
KeystoreTokenStore |
| Rust (an app's shared core) | plumbox-client (Cargo, git) |
your shells open it and pass the callback URL back | yours (on_tokens) |
// Swift
let req = try beginAuthorization(clientId: "dev.jan.notes:ios", redirectUri: "notes://auth/callback",
scopes: [.filesApp])
let callback = try await PlumAuthorizationSession(presentationAnchor: window).start(req)
let cb = parseCallback(callback)
let tokens = try await exchangeCode(baseUrl: cb.iss!, code: cb.code!, state: cb.state,
expectedState: req.state, codeVerifier: req.codeVerifier,
clientId: "dev.jan.notes:ios", redirectUri: "notes://auth/callback")
let box = try PlumClient(baseUrl: cb.iss!, tokens: tokens, clientId: "dev.jan.notes:ios",
tokenStore: KeychainTokenStore(service: "dev.jan.notes"),
onAuthError: { _ in askToReconnect() })
let page = try await box.drive.list(tokens.appFolder!)
// Kotlin
val req = beginAuthorization("dev.jan.notes:android", "notes://auth/callback", listOf(OAuthScope.FILES_APP))
PlumAuthorization.launch(context, req) // Custom Tabs
// …in the Activity that receives notes://auth/callback:
val cb = PlumAuthorization.parseCallback(intent, "notes://auth/callback") ?: return
val tokens = exchangeCode(cb.iss!!, cb.code!!, cb.state, req.state, req.codeVerifier,
"dev.jan.notes:android", "notes://auth/callback")
val box = PlumClient(baseUrl = cb.iss!!, token = tokens.accessToken, refreshToken = tokens.refreshToken,
expiresAt = tokens.expiresAt, appFolder = tokens.appFolder, clientId = "dev.jan.notes:android",
tokenStore = KeystoreTokenStore(context), onAuthError = { askToReconnect() })
val page = box.drive.list(tokens.appFolder!!)
Each package's README has the full quickstart, the security requirements and what differs from the TypeScript names. They are not on SwiftPM tags, Maven or crates.io yet — until then, build from the repository.
If you call the HTTP endpoints above directly instead, the refresh is yours to get right:
keep the refresh token, renew the access token before it expires, save each new refresh token
before you use the new access token (the old one stops working 60 seconds later), never run two
refreshes at once, and send the user through sign-in again on invalid_grant. An app that keeps
only the access token stops working an hour after it connects.
The Plum apps themselves use larger in-repo libraries (im.plum.plumconnect on Android,
PlumConnect under PlumBoxApp/Core/Connect on iOS) that also do box discovery and the
LAN / peer-to-peer transports. They are not meant for other apps.
6. Finding the user's box
Simplest and most reliable: ask the user for their box address (https://pb-1234.plumbox.me).
The SDKs accept only a box address of that form as the issuer, so the sign-in flow needs a real box
— the emulator can check your manifest's clients[], not run the flow. @plumbox/client also ships a relay lookup, and @plumbox/oprf resolves boxes from
an email and password without the relay learning either — that path is what the Plum apps use.
7. Entitlements
GET /api/apps/dev.jan.notes/entitlement
Authorization: Bearer plum_pat_…
{"skus":[{"sku":"pro","kind":"one_time","expires_at":"","active":true}],
"refreshed_at":"2026-09-20T22:14:03Z","stale":false}
A token may read this with service:call:<app_id> (or a broader read scope — files:app is not
one: a folder-only app that checks entitlements asks for service:call:<app_id> too). stale means the
box has not reached the store in 48 hours; keep working and say so quietly. See
Publishing for how SKUs and grants are set up.
8. Get listed
- An app with a
.plu: publish it, and the clients you registered ride along. - An app with no
.plu: register a compatible app with its id, display name and a link, then add its clients. Boxes show these on their own shelf (GET /api/apps/store/compatible), separate from installable apps.