App installations
Build your product on top of Reuzenpanda. With an app installation a customer connects your app to their company profile with one switch, and your app can work for that company from then on: read and change their CRM, conversations, quotations and calendars, run automations in the background, or act for the person who is using your app right now.
- One click for the customer. An administrator installs your app once in Reuzenpanda Hub. No consent screen per user, no redirect flow to build.
- Nothing to store. No refresh tokens and no long-lived credentials per customer. Your app asks for a token when it needs one.
- Small blast radius. A token is valid for one company profile, within fixed scopes, for 15 minutes.
- Works without a person. Scheduled jobs and automations run as your app itself.
- Works for a person. Actions are in that user's name, and every user decides for themselves whether your app may act for them.
- Stay in sync. Events tell your app at once when it is installed, uninstalled, or switched on by a user.
- Standard OAuth 2.0. Any OAuth library that supports the client credentials grant can do this.
It is the same pattern as GitHub App installation tokens. In OAuth terms it is a pre-authorized
client_credentials grant.
Getting access
App installations are for partners, and every app is reviewed before it can be installed.
- Ask. Mail support@reuzenpanda.nl and tell us what your app does, which data it needs and for which customers.
- Review. We look at your use case, the scopes you ask for and how your app handles the data.
- Agreement. Before your app goes live you sign a data processing agreement and a partnership agreement with us.
- Registration. You get a client id, and we record your JWKS URL (or give you a client secret), your scopes, whether your app may act on behalf of users, and optionally the links to your privacy policy and terms.
Your app has to keep to the API terms published at api.reuzenpanda.app (opens in a new tab), including the rate limits, for as long as it is connected. We can check this, also with an audit, and we can suspend or remove an app that does not comply.
Your options at a glance
| Choice | Options |
|---|---|
| How your app proves who it is | A key pair with a public JWKS URL (private_key_jwt, recommended), or a client secret |
| As whom it acts | As itself in a company profile, on behalf of a user in that profile, or both |
| What it can reach | The areas agreed for your app: parts of the public API, and private APIs where your use case calls for them |
| How it stays up to date | Events pushed to your URL, a list of your installations you can ask for, or simply the answer to each token request |
The scopes and whether your app may act on behalf of users are agreed when the app is registered.
How your app acts
| As itself | On behalf of a user | |
|---|---|---|
| Token request | profile_id | profile_id and user_id |
| Requirement | The app is installed on the profile | The app is installed, the user is a member of the profile, and has switched the app on for themselves |
| The token acts as | Your app, within its scopes, in that profile | That user, within the scopes, in that profile |
| Typical use | Automations and scheduled work without a person | Anything a person does in your app |
Whether your app may act on behalf of users is set when the app is registered.
If a request on behalf of a user is refused, do not fall back to acting as the app itself: that would ignore the user's choice.
Scopes and what they mean
Scopes are per area of the platform, such as the CRM, the calendar or conversations. A scope has the form
api:<area>:<action>, and reading and changing an area are separate scopes.
Which areas your app gets is agreed when it is registered, based on what it needs. That can include areas that are not in the public reference. An installation has that fixed set: a token never has more than the installation, and your app can ask for less per token.
What to keep in mind:
- Ask for the narrowest set that does the job. The customer sees what your app may do before installing it.
- A scope applies to the whole company profile. On behalf of a user it is not limited by that user's role in the hub.
- Some areas let your app act in the company's name, such as sending messages or booking appointments. We look at those more closely in the review.
- Never available: administrator or support rights, access to other company profiles, and anything about a user's own account (password, two-factor settings).
- Data your app reads leaves Reuzenpanda. Your own privacy policy and terms apply to what you do with it.
Installing and switching on
Before anyone installs your app or switches it on for themselves, Reuzenpanda Hub shows what they agree to:
- What your app may do. The areas and rights of the installation are always shown. They cannot be hidden.
- What that means. The rights apply to the whole company profile, and data your app reads leaves Reuzenpanda.
- Your privacy policy and terms. If you give us links to them, they are shown at this point, so people can read what you do with their data before they agree. Both links are optional.
How it works for the customer:
- Installing. The owner of the company profile, or a user who may manage API keys, installs the app in Reuzenpanda Hub under Settings → API keys → Connected apps. The scopes of the installation are fixed at that moment. From then on the app can act as itself in that profile.
- On behalf of a user is off by default. Every user switches it on for themselves, per company profile, under On your behalf, after seeing the same overview. Whoever installs the app is switched on straight away.
- Switching off. A user switches it off in the same place. Nobody can switch it on or off for someone else.
- Uninstalling. An administrator removes the app from the whole profile.
- Only in the hub. Installing and switching on cannot be done through the API.
- New scopes. If your app gets an extra scope later, it applies to a profile after the app is installed there again.
What you need
- The client id we give you. Send it as
client_idin every token request. - A way to prove that your app is your app. Pick one:
- A key pair (recommended). An EC P-256 key for ES256, and a public JWKS URL (https) that serves the
public key as a JWK Set. You send us the URL; the private key never leaves your systems and nothing secret is
exchanged. We fetch your keys with a
User-Agentthat starts withReuzenpanda-IdP/1.0. To rotate, publish the new key next to the old one, switch over, and remove the old one. An RSA key (RS256) is possible on request; an app uses one algorithm. - A client secret. Simpler to start with: we give you a secret and you send it with each token request. It is a long-lived shared secret, so store it like a password; rotating it means asking us for a new one.
- A key pair (recommended). An EC P-256 key for ES256, and a public JWKS URL (https) that serves the
public key as a JWK Set. You send us the URL; the private key never leaves your systems and nothing secret is
exchanged. We fetch your keys with a
- Per request the profile id, and for a user the user id, as Reuzenpanda knows them.
Everything else on this page is the same for both.
Requesting a token
With a key pair:
POST https://idp.reuzenpanda.nl/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
client_id=<your client id>
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<signed JWT>
scope=api:<area>:read
profile_id=<uuid of the company profile>
user_id=<uuid of the user> (only on behalf of a user)client_id is required, although RFC 7523 makes it optional.
With a client secret, the client id and secret go in the Authorization header (HTTP Basic) and the assertion
fields are left out:
POST https://idp.reuzenpanda.nl/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 of client_id:client_secret>
grant_type=client_credentials
scope=api:<area>:read
profile_id=<uuid of the company profile>
user_id=<uuid of the user> (only on behalf of a user)The client assertion (key pair only)
The assertion is a JWT that your app signs with its private key (ES256). Use the raw r‖s signature format that
JWS prescribes, not DER.
| Claim | Value |
|---|---|
iss and sub | your client id |
aud | the token endpoint: https://idp.reuzenpanda.nl/oauth2/token |
iat | now |
exp | at most a few minutes ahead; 60 seconds is enough |
jti | a unique value per request |
The JWT header carries alg: ES256 and the kid of the key on your JWKS URL.
The answer
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 899,
"scope": "api:<area>:read"
}There is no refresh token. When the token is about to expire, ask for a new one.
Refusals
| HTTP | error | Meaning |
|---|---|---|
| 400 | invalid_grant | The installation does not allow this token. error_description says why (see below). |
| 400 | invalid_request | profile_id is missing or is not a UUID, or a required parameter of the request is missing. |
| 400 | invalid_scope | Your app asked for a scope it does not have. |
| 401 | invalid_client | Your app could not be identified: the assertion (signature, algorithm, audience, expiry) or the client secret was not accepted. |
For invalid_grant, error_description has the form installation token refused: <REASON>:
| Reason | Meaning |
|---|---|
NOT_INSTALLED_ON_PROFILE | The app is not (or no longer) installed on this profile. |
SCOPE_NOT_INSTALLED | The installation does not have this scope; the app has to be installed again. |
MAY_NOT_ACT_AS_MEMBER | This app may not act on behalf of users. |
NOT_A_MEMBER, USER_NOT_FOUND | The user does not exist or is not a member of the profile. |
NOT_OPTED_IN | The user has not switched on On your behalf. |
Do not keep retrying after invalid_grant. Remember the refusal for a few minutes and tell the user what to do,
for example: switch on On your behalf in the hub.
What is in the token
The access token is an RS256 JWT, valid for 15 minutes. You can verify it against our public keys; the JWKS URL is
in the authorization server metadata (opens in a new tab)
(jwks_uri).
| Claim | As itself | On behalf of a user |
|---|---|---|
iss | https://idp.reuzenpanda.nl | https://idp.reuzenpanda.nl |
sub | service:client:<client id> | <user id> |
rp_subject_type | service | user |
rp_company_profile_id | the profile of the installation | the profile of the installation |
rp_user_id | absent | the user |
rp_installation_id | the installation | the installation |
rp_token_kind | installation | installation |
aud | contains your client id | contains your client id |
scope | the granted scopes | the granted scopes |
exp | 15 minutes | 15 minutes |
Ignore claims you do not know; more may be added.
The scopes decide what the token may do. On behalf of a user, actions are in that user's name, but the token is not limited by that user's role in the hub. Apply your own rules where that matters.
Using the token
Send the token as a Bearer token, as with any OAuth access token:
Authorization: Bearer <access_token>The public routes are in the reference at api.reuzenpanda.app (opens in a new tab). Each route asks for
a scope, see Scopes; without it the answer is 401 or 403.
Every call stays within the company profile of the token. Rate limits apply per installation, and per user when your app acts on behalf of one.
Revoking and lifetimes
- Uninstalling the app, switching On your behalf off, or leaving the profile stops the next token request.
- A token that was already issued stays valid until it expires: at most 15 minutes.
- Keep tokens in memory only, per profile (and per user), and renew them shortly before they expire.
- If your private key leaks, replace it on your JWKS URL right away and let us know. If a client secret leaks, ask us for a new one at once.
Code examples
Node 18 or newer, no extra packages.
Key pair and JWK Set
import { generateKeyPairSync } from "node:crypto";
const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
const pem = privateKey.export({ type: "pkcs8", format: "pem" }); // keep secret
const jwk = { ...publicKey.export({ format: "jwk" }), use: "sig", alg: "ES256", kid: "2026-11" };
const jwks = JSON.stringify({ keys: [jwk] }); // publish on your JWKS URLClient assertion
import { createPrivateKey, randomUUID, sign } from "node:crypto";
const TOKEN_URL = "https://idp.reuzenpanda.nl/oauth2/token";
const b64 = (v) => Buffer.from(v).toString("base64url");
function clientAssertion(clientId, pem, kid) {
const now = Math.floor(Date.now() / 1000);
const header = { alg: "ES256", typ: "JWT", kid };
const claims = { iss: clientId, sub: clientId, aud: TOKEN_URL, iat: now, exp: now + 60, jti: randomUUID() };
const input = `${b64(JSON.stringify(header))}.${b64(JSON.stringify(claims))}`;
const signature = sign("sha256", Buffer.from(input), { key: createPrivateKey(pem), dsaEncoding: "ieee-p1363" });
return `${input}.${b64(signature)}`;
}Requesting a token
async function installationToken(clientId, pem, kid, scope, profileId, userId) {
const body = new URLSearchParams({
grant_type: "client_credentials",
client_id: clientId,
client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
client_assertion: clientAssertion(clientId, pem, kid),
scope,
profile_id: profileId
});
if (userId) body.set("user_id", userId); // only on behalf of a user
const res = await fetch(TOKEN_URL, { method: "POST", body });
const json = await res.json();
if (res.ok) return json; // { access_token, expires_in: 899, ... }
if (json.error === "invalid_grant") return null; // not installed, or not switched on
throw new Error(`${res.status} ${json.error} ${json.error_description ?? ""}`);
}With a client secret instead
async function installationTokenWithSecret(clientId, clientSecret, scope, profileId, userId) {
const body = new URLSearchParams({ grant_type: "client_credentials", scope, profile_id: profileId });
if (userId) body.set("user_id", userId);
const res = await fetch("https://idp.reuzenpanda.nl/oauth2/token", {
method: "POST",
headers: { Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}` },
body
});
const json = await res.json();
if (res.ok) return json;
if (json.error === "invalid_grant") return null;
throw new Error(`${res.status} ${json.error} ${json.error_description ?? ""}`);
}Using the token
// Any route from the reference at api.reuzenpanda.app, here with API_BASE as the base URL listed there
const res = await fetch(`${API_BASE}/<route>`, {
headers: { Authorization: `Bearer ${token}` }
});Caching
const tokens = new Map(); // "profile|user" -> { token, expiresAt }
const refusedUntil = new Map(); // "profile|user" -> time
async function tokenFor(profileId, userId) {
const key = `${profileId}|${userId ?? ""}`;
if ((refusedUntil.get(key) ?? 0) > Date.now()) return null;
const cached = tokens.get(key);
if (cached && cached.expiresAt > Date.now()) return cached.token;
const made = await installationToken(CLIENT_ID, PEM, KID, SCOPE, profileId, userId);
if (!made) {
refusedUntil.set(key, Date.now() + 300_000); // remember a refusal for five minutes
return null;
}
tokens.set(key, { token: made.access_token, expiresAt: Date.now() + (made.expires_in - 60) * 1000 });
return made.access_token;
}Events
Without events your app only learns that something changed at its next token request. With events it hears at once: a user who switches On your behalf on can continue straight away, and after an uninstall your app drops its cached token instead of using it for another 15 minutes.
You give us an events URL (https). An event is a Security Event Token (opens in a new tab) (RFC 8417): a JWT signed by Reuzenpanda with the same key that signs access tokens. You verify it against our JWKS. There is no shared secret.
| Event | When | Extra fields |
|---|---|---|
installation.created | the app is installed on a profile | scopes |
installation.deleted | the app is uninstalled | reason |
member.enabled | a user switches On your behalf on | user_id |
member.disabled | a user switches it off | user_id, reason |
verification | a test event, on your request | state |
In the token the event type is the URI https://idp.reuzenpanda.nl/apps/events/<event>.
Delivery
Events are pushed with one HTTP request per event (RFC 8935 (opens in a new tab)):
POST <your events URL>
Content-Type: application/secevent+jwt
Accept: application/json
eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9.eyJpc3MiOi...The payload of the JWT, here for a user who switches the app on:
{
"iss": "https://idp.reuzenpanda.nl",
"aud": "<your client id>",
"iat": 1794900000,
"jti": "0b6f2c1e-6f0a-4d0e-9a55-3c1f7a2b9d41",
"events": {
"https://idp.reuzenpanda.nl/apps/events/member.enabled": {
"installation_id": "3f2a9c1e-7b4d-4e8a-9c2f-5d1e8a7b6c40|<your client id>",
"profile_id": "3f2a9c1e-7b4d-4e8a-9c2f-5d1e8a7b6c40",
"user_id": "9d4c2b7a-1e6f-4a3b-8c5d-2f7e9a1b3c58"
}
}
}| Field | Meaning |
|---|---|
iss | Reuzenpanda's identity provider; use it to find the JWKS |
aud | your client id; refuse an event for another app |
iat | when it happened. There is no exp: an event describes the past |
jti | the unique id of the event; deduplicate on it |
events | exactly one event, keyed by its type |
Rules:
- Any
2xxanswer counts as received. We wait at most 5 seconds for an answer. - After a failure we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours.
- An event can arrive twice, and the order is not guaranteed. Every event stands on its own.
- Events carry ids only, no names or e-mail addresses.
- Events speed things up; they guarantee nothing. The token request stays the only hard check.
Verifying an event
import { createPublicKey, verify } from "node:crypto";
const ISSUER = "https://idp.reuzenpanda.nl";
const seen = new Set(); // in production: a table with a retention period
async function readEvent(jwt, clientId) {
const [h, p, sig] = jwt.split(".");
const header = JSON.parse(Buffer.from(h, "base64url"));
const claims = JSON.parse(Buffer.from(p, "base64url"));
const { jwks_uri } = await (await fetch(`${ISSUER}/.well-known/oauth-authorization-server`)).json();
const { keys } = await (await fetch(jwks_uri)).json(); // cache this; fetch again for an unknown kid
const jwk = keys.find((k) => k.kid === header.kid);
const ok =
jwk &&
header.alg === "RS256" &&
verify("RSA-SHA256", Buffer.from(`${h}.${p}`), createPublicKey({ key: jwk, format: "jwk" }), Buffer.from(sig, "base64url"));
const aud = [].concat(claims.aud ?? []);
if (!ok || claims.iss !== ISSUER || !aud.includes(clientId)) throw new Error("invalid event");
if (seen.has(claims.jti)) return null; // already handled: still answer 2xx
seen.add(claims.jti);
const [[type, data]] = Object.entries(claims.events);
return { type: type.split("/apps/events/")[1], ...data }; // { type: "member.enabled", profile_id, ... }
}What to do with an event:
member.enabled: forget the remembered refusal for that profile and user.member.disabled,installation.deleted: drop the cached token and do not ask again.
Asking about your installations
Besides events, your app can ask which installations it has, also without an events URL. Request an
app token: the same token request as above, with scope=installations:read and without
profile_id. That token only works on the identity provider.
| Call | What it does |
|---|---|
GET https://idp.reuzenpanda.nl/api/installations | the profiles your app is installed on, with scopes and the users who switched it on. Use it as a safety net for missed events |
POST https://idp.reuzenpanda.nl/api/installations/verification | asks for a test event on your events URL; the state you send comes back in the event |
{
"client_id": "<your client id>",
"installations": [
{
"installation_id": "3f2a9c1e-7b4d-4e8a-9c2f-5d1e8a7b6c40|<your client id>",
"profile_id": "3f2a9c1e-7b4d-4e8a-9c2f-5d1e8a7b6c40",
"scopes": ["api:<area>:read"],
"status": "active",
"installed_at": "2026-11-17T09:12:44Z",
"acts_as_members": true,
"members": [{ "user_id": "9d4c2b7a-1e6f-4a3b-8c5d-2f7e9a1b3c58", "enabled_at": "2026-11-17T09:12:44Z" }]
}
]
}Standards
| Part | Standard |
|---|---|
| Token request without a user present | RFC 6749 (opens in a new tab) §4.4 (client credentials grant) |
| Client authentication with a key pair | RFC 7523 (opens in a new tab) §2.2 and §3, OpenID Connect Core §9 (private_key_jwt) |
| Client authentication with a secret | RFC 6749 (opens in a new tab) §2.3.1 (client_secret_basic) |
| Your public key | RFC 7517 (opens in a new tab) (JWK Set) |
| Access token format | RFC 9068 (opens in a new tab), with our own claims prefixed rp_ |
| Sending the token | RFC 6750 (opens in a new tab) (Bearer) |
profile_id and user_id | extension parameters (RFC 6749 (opens in a new tab) §8.2); our own addition |
| Error answers | RFC 6749 (opens in a new tab) §5.2 |
| Endpoint discovery | RFC 8414 (opens in a new tab), RFC 9728 (opens in a new tab) |
| Events | RFC 8417 (opens in a new tab) (Security Event Token), RFC 8935 (opens in a new tab) (push delivery) |
Questions? Reach out to support@reuzenpanda.nl.