Organisation Platform Integration

Use your organisation’s structure and job titles inside your app

What is the Organisation Platform?

The Organisation Platform is where your organisation keeps its structure: the org units (divisions, branches, teams) that form a tree of any depth, the designations (business titles such as “Branch Manager”) people hold, and which person holds which designation at which unit.

Connecting it gives your generated app read access to that data, so you don’t rebuild it.

Perfect for:

Showing an org chart or “who reports where”
Looking up a person’s job title and unit when they sign in
Giving people roles in your app based on the designations they hold
Partitioning your app’s own data by organisation unit

The connector is read-only and pull-based. Your app asks the Organisation Platform for data when it needs it; the Organisation Platform stays the system of record.

What You’ll Need

Nothing, for auto-provision

Buildpad requests a read-only key for the Xtremax organisation for you. You don’t pick an organisation, and you don’t need an account on the Organisation Platform.

Or an API key, to bring your own

To read a different organisation or unit, a platform admin or an Organization Unit Admin at that unit (or above) issues a key from the API keys icon on the unit’s row in the Org Units sidebar of the Organisation Platform. It starts with orgapi_ and is shown only once. A key reads its unit and everything under it.

The Organisation Platform address is set by Buildpad for the environment. You never enter it.

Step 1: Connect the Organisation Platform

Open your project → Connectors in the sidebar (or check the Organisation Platform card during project creation).
Click Connect.
Choose a mode:
- Auto-provision (default) — Buildpad requests a read-only key for the Xtremax organisation, one per project, and stores it. When it is done, the card shows Connected, or Error if it failed.
- Bring your own key — paste an Organisation API Key issued for your organisation, or one of its units. Buildpad checks the key when you click Connect. The key must start with orgapi_. If the Organisation Platform rejects the key, you see “The Organisation Platform rejected this API key.” If Buildpad cannot reach the Organisation Platform, the connection is not blocked.
For Auto-provision, click Auto-provision now. For Bring your own key, click Connect.

This stores two things for your project: ORG_PLATFORM_API_KEY and ORG_PLATFORM_URL. The URL isn’t a field you fill in. Buildpad sets it for the environment, and the connect form can’t be tricked into overriding it.

An auto-provisioned key is always read-only and always reaches the Xtremax organisation, whatever your own role is on the Organisation Platform. The onboarding and personal-data scopes are never granted automatically: if your app needs to onboard people or read their mobile number or date of birth, ask an Organisation Platform administrator to enable it for the key (see the questions below). A key reaches exactly one unit and its subtree, nothing above or beside it. If your app needs another unit, paste a key issued for it.

Disconnecting an auto-provisioned connector also revokes its key on the Organisation Platform. If the revocation fails, the connector is kept and you can try again.

Step 2: Tell the Agent What You Want

Once connected, your coding assistant already knows the API’s shape and rules. Describe the outcome, not the endpoints.

Example 1: Org chart


Add an "Organisation" page that shows our org units as an expandable
tree, using the connected Organisation Platform.

Keep it read-only. Load the tree on the server so the API key never
reaches the browser.

Example 2: Show a person’s title and unit


On the profile page, show the signed-in user's designations and the
unit they hold each one at, from the Organisation Platform.

If the lookup fails or returns nothing, still let them in and just
hide the section.

Example 3: Roles from designations


Give people a role in this app based on their designation:
- "Branch Manager" → manager
- "Accountant" → finance

Reconcile when they sign in. Never remove a role that an admin
already gave them, and let admins edit the mapping from a settings page.

Example 4: Rule-based role assignment (Automation)


Add an Automation > Role assignment screen in the admin area where an admin writes rules
like "include Branch Managers under the Finance unit, exclude
contractors, give the Manager role".

Use the @xtremax/organisation-platform package for the rule engine,
and build the screens the reference apps use: a list of rules with
priority arrows and toggles, one form to create or open a rule, and a
Test rules drawer. Apply the rules when people sign in, and never take
away a role that an admin gave someone by hand.

Your assistant uses the @xtremax/organisation-platform package by default for anything that talks to the Organisation Platform: its typed server client, the rule engine, and the headless rule builder core. It builds its own rule screens on that core. It does not use the package’s ready-made rule builder screen unless you ask for it. It pins the package to a minor version and keeps the API key on the server.

Under the hood: your assistant reads a bundled reference covering the endpoints, the retry rules, and the safe way to turn designations into roles, including the rule engine, how rules are stored and saved, and the sign-in checks that make a missing or broken rule grant nothing and remove nothing. It joins on ids and emails, never on names.

Example 5: Import people and review leavers


On the admin Users screen, add "Import from Organisation Platform"
and an "Offboarding review", using the connected Organisation Platform.

The import shows a preview first. Nothing changes until an administrator confirms. Then it creates an account (email and name, no password, no role) for each designation holder who has no account, in batches of 10. It also records the listed people who already had an account. The offboarding review looks only at people an import recorded. It lists those with an active account on a company email domain that the Organisation Platform no longer knows. An administrator ticks each person. The app checks each one again, then suspends the account. It never deletes it. A suspended account cannot sign in. On a Supabase project, your assistant uses tested code for these tools and for Automation > Role assignment. A Buildpad Engine project has no such code yet, so the assistant builds them to the same rules.

Step 3: Test the Connection

Start the app

Run pnpm dev. Your assistant writes the connection values to .env.local.

Load the data

Open the page that reads from the Organisation Platform. You should see your org units or the person’s designations.

Check a person with no designations

Look up someone who holds none. The page should still work. An empty result and an unknown person look the same to the API.

Repeat after deploying

The values connected here don’t automatically reach your deployed app. Ask your assistant to push them and redeploy, then re-test on the live URL.

Common Questions

Is the API key a secret?

Yes. Unlike a widget key, it is a bearer credential with no expiry. It must only be used in server-side code and never in a client component, a NEXT_PUBLIC_ variable, or a log.

What’s the difference between a designation and an access role?

A designation is a job title (“Branch Manager”). An access role is permission inside the Organisation Platform itself. This connector exposes designations. What a designation lets someone do in your app is a mapping you own.

Can my app create people or assign designations?

Not with an auto-provisioned key, which is read-only. The Organisation Platform has one write endpoint, but it needs a separate key scope (“Allow onboarding”). Ask an Organisation Platform administrator (a platform admin, or the Organization Admin of Xtremax) to turn it on for your project’s key, which is named Buildpad · {organization} / {project} (by {you}) in the API keys panel. The key stays the same, so there is nothing to reconnect or redeploy. Your coding assistant will tell you when a feature needs it.

Can my app see people’s mobile numbers or dates of birth?

Only if the key was given the personal data scope, and an auto-provisioned key isn’t. Without it those two fields are left out entirely. Ask an Organisation Platform administrator to turn on “Allow personal data” for your project’s key. Country, time zone, and who a person reports to are always included.

Will my app hear about changes automatically?

No. There are no webhooks. Your app reads the data when it needs it, or follows the change feed on a schedule you choose.

How do I rotate the key?

Issue a new key in the Organisation Platform, reconnect it here, push the new value to your deployed app and redeploy. A revoked key stops working immediately, with no grace period.

Something Not Working?

Every Call Fails With 401

The key is missing, unknown, or revoked, and the API deliberately doesn’t say which. Tell the agent:


Calls to the Organisation Platform return 401.

Check that ORG_PLATFORM_API_KEY and ORG_PLATFORM_URL are set in
.env.local, then tell me; I'll confirm with the Organisation Platform
admin that the key is still active.

A Unit or Person Isn’t Found

A 404 means either “doesn’t exist” or “outside your key’s scope”. Check that the key was issued for a unit that contains it. A key scoped to one department can’t see anything outside that department.

Works Locally but Not Deployed

The deployed app has no values to read. Ask the agent to push ORG_PLATFORM_API_KEY and ORG_PLATFORM_URL to your deployed app’s environment and redeploy.