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, ::1 or localhost, and the box matches any port, so you do not have to register the ephemeral one (RFC 8252 §7.3);
  • https is 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-only allow_https_redirects flag, 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 .plu cannot declare it in its manifest permissions.

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.

  1. Build a verifier (43–128 characters), a challenge base64url(SHA-256(verifier)) and a random state.
  2. 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 own GET /authorize using 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.
  3. The user approves; the box redirects to your redirect_uri with code, state and iss (the box's own address). Codes are one-time and live 5 minutes.
  4. 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_in runs 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 says invalid_grant, reconnect.
  • 403: the credential is fine, the request is not allowed — a scope you were not granted, or a path outside your files:app folder. 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.