Api Documentation
App installations

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.

  1. Ask. Mail support@reuzenpanda.nl and tell us what your app does, which data it needs and for which customers.
  2. Review. We look at your use case, the scopes you ask for and how your app handles the data.
  3. Agreement. Before your app goes live you sign a data processing agreement and a partnership agreement with us.
  4. 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

ChoiceOptions
How your app proves who it isA key pair with a public JWKS URL (private_key_jwt, recommended), or a client secret
As whom it actsAs itself in a company profile, on behalf of a user in that profile, or both
What it can reachThe 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 dateEvents 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 itselfOn behalf of a user
Token requestprofile_idprofile_id and user_id
RequirementThe app is installed on the profileThe app is installed, the user is a member of the profile, and has switched the app on for themselves
The token acts asYour app, within its scopes, in that profileThat user, within the scopes, in that profile
Typical useAutomations and scheduled work without a personAnything 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

  1. The client id we give you. Send it as client_id in every token request.
  2. 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-Agent that starts with Reuzenpanda-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.
  3. 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.

ClaimValue
iss and subyour client id
audthe token endpoint: https://idp.reuzenpanda.nl/oauth2/token
iatnow
expat most a few minutes ahead; 60 seconds is enough
jtia 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

HTTPerrorMeaning
400invalid_grantThe installation does not allow this token. error_description says why (see below).
400invalid_requestprofile_id is missing or is not a UUID, or a required parameter of the request is missing.
400invalid_scopeYour app asked for a scope it does not have.
401invalid_clientYour 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>:

ReasonMeaning
NOT_INSTALLED_ON_PROFILEThe app is not (or no longer) installed on this profile.
SCOPE_NOT_INSTALLEDThe installation does not have this scope; the app has to be installed again.
MAY_NOT_ACT_AS_MEMBERThis app may not act on behalf of users.
NOT_A_MEMBER, USER_NOT_FOUNDThe user does not exist or is not a member of the profile.
NOT_OPTED_INThe 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).

ClaimAs itselfOn behalf of a user
isshttps://idp.reuzenpanda.nlhttps://idp.reuzenpanda.nl
subservice:client:<client id><user id>
rp_subject_typeserviceuser
rp_company_profile_idthe profile of the installationthe profile of the installation
rp_user_idabsentthe user
rp_installation_idthe installationthe installation
rp_token_kindinstallationinstallation
audcontains your client idcontains your client id
scopethe granted scopesthe granted scopes
exp15 minutes15 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 URL

Client 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.

EventWhenExtra fields
installation.createdthe app is installed on a profilescopes
installation.deletedthe app is uninstalledreason
member.enableda user switches On your behalf onuser_id
member.disableda user switches it offuser_id, reason
verificationa test event, on your requeststate

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"
    }
  }
}
FieldMeaning
issReuzenpanda's identity provider; use it to find the JWKS
audyour client id; refuse an event for another app
iatwhen it happened. There is no exp: an event describes the past
jtithe unique id of the event; deduplicate on it
eventsexactly one event, keyed by its type

Rules:

  • Any 2xx answer 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.

CallWhat it does
GET https://idp.reuzenpanda.nl/api/installationsthe 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/verificationasks 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

PartStandard
Token request without a user presentRFC 6749 (opens in a new tab) §4.4 (client credentials grant)
Client authentication with a key pairRFC 7523 (opens in a new tab) §2.2 and §3, OpenID Connect Core §9 (private_key_jwt)
Client authentication with a secretRFC 6749 (opens in a new tab) §2.3.1 (client_secret_basic)
Your public keyRFC 7517 (opens in a new tab) (JWK Set)
Access token formatRFC 9068 (opens in a new tab), with our own claims prefixed rp_
Sending the tokenRFC 6750 (opens in a new tab) (Bearer)
profile_id and user_idextension parameters (RFC 6749 (opens in a new tab) §8.2); our own addition
Error answersRFC 6749 (opens in a new tab) §5.2
Endpoint discoveryRFC 8414 (opens in a new tab), RFC 9728 (opens in a new tab)
EventsRFC 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.