Examples

Every SDK ships a runnable example app, so you can watch the SDK make real calls against the live platform before you write a line of integration. Install the SDK with your package manager, start the example, complete a short checklist in the allus portal, click a scenario — and the page shows the result plus the exact SDK methods that produced it.

All six examples share one browser UI — the example test suite — and a thin per-language backend, so you see the same scenario cards whichever language you pick. They are localhost teaching apps, not deployment templates: the point is to see the SDK surface in action and copy the calls into your own service.

Pick your language in the tabs of any code block below — the choice is remembered across every code block on every page.

The shortest path

Install the SDK with your language's package manager — for PHP, Python and TypeScript the example suite ships inside the package, so that one command gets you both (step 1).
Start it with your language's start command; one server serves all three scenario families on http://localhost:8091 (step 2).
Complete the scenario's checklist in the browser — it names the exact allus portal steps (register an app, select a service, download a key), gives the intended value for every control on each of those forms including the ones to leave alone, and lists any phone prerequisites (step 3).
Click the scenario's action (Sign in, Connect, Run challenge, …).
Inspect the result — the data area shows the typed values, and “what just happened” lists the SDK calls that produced them (step 4).

1. Install the SDK

One package-manager command is the shortest path. For PHP, Python and TypeScript the example suite ships inside the published package, so installing the SDK is also how you get the example — if the SDK is already in your project, you already have it. The three other languages take the repository route (see the note under the tabs). Installing the SDK for your own integration is covered on the SDKs and Getting started pages.

# Requires Python ≥ 3.11 — the example suite ships inside the package.
# A system/Homebrew Python refuses a bare `pip install` (PEP 668) — install
# into a virtualenv, which is also where the launcher will need write access:
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install allus-company-data

# Requires Node ≥ 18 — the example suite ships inside the package
npm install @allus-fyi/company-data

# Requires Go ≥ 1.26 — the example suite is its own nested Go module, so it is
# NOT part of what `go get` fetches. Clone the SDK's public repository instead:
git clone https://github.com/allus-fyi/company-data-go

# Requires .NET SDK 8+ — not on NuGet yet, so get the SDK (and the example
# suite it carries) from its public repository:
git clone https://github.com/allus-fyi/company-data-csharp.git

# Requires JDK 21 and Maven on your PATH — not on Maven Central yet, so build
# the SDK from its public repository (this also gets you the example suite):
git clone https://github.com/allus-fyi/company-data-java.git
cd company-data-java
mvn -q install -DskipTests    # installs the SDK into your local Maven repository

# Requires PHP ≥ 8.1 with ext-openssl + ext-json — the suite ships inside the package
composer require allus/company-data

Three languages take the repository route instead. C# and Java are not published to NuGet / Maven Central yet, and Go's example suite is a separate nested module — that is what keeps the example's dependencies out of the SDK module — so go get gives you the SDK but not the suite. For those three, clone the SDK's public repository, which carries the suite under examples/. For PHP, Python and TypeScript the registry package already contains it; cloning the repo works there too if you prefer.

2. Start the example

One start, one port, all three scenario families in one browser portal — no per-family process to juggle. The launcher wipes its previous run state, downloads the pinned frontend bundle and verifies its checksum on first start, then serves port 8091 on all interfaces and prints every URL it is reachable on. That first fetch needs tar on your PATH for PHP, TypeScript and Java (PHP and Java also shell out to curl); Python, Go and C# download and unpack in-process.

# the suite sits inside the installed package — cd to it, then start it
cd "$(python -c 'import allus_company_data.examples as e, os; print(os.path.dirname(e.__file__))')"
python bin/start.py            # -> http://localhost:8091

# The launcher creates its own virtualenv next to the suite and installs the
# example's dependencies, so install into a virtualenv you can write to.
# From a clone instead: cd company-data-python/examples && python bin/start.py

# the suite sits inside the installed package
cd node_modules/@allus-fyi/company-data/examples
npm install                    # the example's own dependencies (tsx + the OIDC client)
npm start                      # -> http://localhost:8091

# From a clone instead:
#   cd company-data-typescript && npm install && npm run build   # build the SDK first
#   cd examples && npm install && npm start

cd company-data-go/examples
go run .                       # -> http://localhost:8091

cd company-data-csharp/examples
dotnet run                     # -> http://localhost:8091

# after the `mvn -q install -DskipTests` from step 1
cd company-data-java/examples
mvn -q compile exec:java       # -> http://localhost:8091

# the suite sits inside the installed package
cd vendor/allus/company-data/examples
composer start                 # -> http://localhost:8091
                               # (installs the example's own dependencies on first run)

# From a clone instead: cd company-data-php/examples && composer start

Open http://localhost:8091 and pick a scenario. Port 8091 is deliberately the same for every SDK's example — one browser origin, so a setup you type once carries across languages — which does mean two SDKs' examples can't run side by side; override with PORT=<n>. Within one SDK there is nothing to juggle: its single server already serves every family.

Testing from a phone or another machine? Every example binds all interfaces, so any device on the same network can reach it — startup prints the exact http://<your-lan-ip>:8091 URL next to the localhost one. Open that URL on the phone and save the scenario's setup there: the redirect URI the backend writes follows the origin you used, so register that same http://<your-lan-ip>:8091/callback on the OAuth app. Binding all interfaces also means anyone on your network can reach the example, and its setup panels accept and store real credentials under .runtime/config/ — OAuth and data-client secrets, private-key PEMs and their passphrases, and webhook signing secrets. It is a local development demo, not a hardened service: run it only on a network you trust, and only with sandbox credentials.

Moving a whole setup to that phone. A setup lives in the browser that typed it, so the sidebar carries two buttons above Clear all: Save all stores this browser's whole setup on the example backend, and Restore all loads it into another browser pointed at the same backend. The backend keeps it as an opaque blob and never runs anything off it; it sits with the rest of .runtime/, so restarting the example or pressing Clear all drops it. After restoring, press Save in each scenario you want to run — that is what writes its config file on this device, with this device's own redirect URI — and register that redirect URI on the OAuth app as above.

3. Set the scenario up in the portal

Every scenario is setup-first: its card lists the exact steps and the fields to fill before it will run. You do those steps in the allus portal at portal.allus.fyi — register an OAuth app or a data client, pick the service, download its private-key PEM — and paste the results into the card. The portal guides walk through each of those screens.

Under the checklist, each scenario shows a table per portal form it sends you to, with one row for every control that form renders — what to set, and equally what to leave alone and why. Nothing on those forms is left for you to guess: a control that matters says so (the OIDC scenarios need Claims in the id_token on Plaintext, or the login succeeds and carries no email and no name), and a control that does not matter says that too.

The default target is the deployed allus platform, so there is nothing to stand up locally for the run itself and a physical phone with the allme app reaches everything naturally. For the identity scenarios, register as the OAuth app's redirect URI the one matching the origin you open the portal on — the backend writes whichever origin your browser used into the scenario's config file, so the two must match: http://localhost:8091/callback when you browse from the machine running the example, http://<your-lan-ip>:8091/callback when you drive it from a phone (adjust if you changed PORT). Running against a local stack instead is an optional secondary target — switch the scenario's advanced inputs to your local URLs.

4. Watch what happened

Result / data area — the typed values the SDK returned, as labelled key → value rows.
Raw view — the full response object, collapsible.
“What just happened” — the exact SDK methods the scenario invoked, in order, linking the matching SDK README chapter.
Browser console — request/response detail for the curious.

What the suite demonstrates

Scenario families as sections — identity (sign-in / OIDC / 2FA), company-data (data-client reads, request fields, the change feed, webhooks and documents) and flow (contract flows) each get their own section in the one portal; a single server start serves them all.
One shared UI across every SDK — the same scenario cards, so a setup you enter once carries across languages.
A thin per-SDK backend — most of each example is the shared frontend; each language ships only a small backend that calls its SDK's intended top-level surface, so you can open a handler file and see exactly which call implements each flow.

Configuration — you type it in the browser

You never hand-create or edit a config file. Each scenario's setup panel collects the credentials and keys it needs (a client id/secret, a PEM file-picker, a share code…), and on Save the backend writes them into the real SDK config file the run executes off — the same shape you would wire in production. The panel shows the written path so you can open and read it; Run then builds the SDK from that file and runs off it. Clearing a scenario removes the config file and its key.

Webhooks

Every SDK's company-data example includes a webhook scenario. Like the other scenarios it is setup-first: register a webhook on your service in the portal and paste its webhook id and one-time HMAC secret into the scenario before starting it — the run refuses to start without them. Set encrypt_payload OFF (the example holds no account private key).

Once started, the scenario also polls the change feed on every poll, so events stay visible even when no inbound delivery reaches your machine, and results label whether each event arrived through webhook or feed.

A public tunnel is optional — needed only to receive real inbound deliveries on your localhost:

cloudflared tunnel --url http://localhost:8091

Use the printed public URL with /webhook appended as the webhook's URL when you register it, and keep the tunnel running while you test. A webhook URL must be https on port 443 to a public address, so a localhost URL is refused on every stack.

How it is wired (for maintainers)

Ordinary developers can skip this. Each example serves a shared, released frontend bundle — fetched once at a pinned, checksummed version — plus a small demo-backend contract: a handful of endpoints the frontend speaks. GET /api/meta lists the scenarios; a config endpoint saves your settings; a start endpoint runs one off the saved config; a poll endpoint returns the outcome. The frontend renders setup-first scenario cards and calls only those endpoints; the backend calls only the SDK's intended top-level surface. That shared contract is what makes the six examples strictly comparable.

Start here

Build

CRM integrations

Portal

Reference