Advanced: Portal API

Everything you configure in the allus portal UI — services, request fields, what you share back, webhooks, API clients — is backed by an HTTP API. This page is for teams that prefer to manage that configuration as code instead of clicking through the portal.

Portal API vs. service API

allus exposes two distinct API surfaces. They use different OpenAPI specs, different auth, and never overlap. Both are region-bound in the same way: you authenticate at the global front door and address every authenticated call to the api_url the token response returned — see Regions.

A registered service API client cannot call the portal API — its whitelist covers the service data patterns only, and none of them reach /api/services/*. Conversely the portal allus-client cannot read /api/company-data/*. They are deliberately separate.

Authenticating to the portal API

The portal API is authenticated as your company portal account through the public allus-client using the OAuth authorization-code + PKCE flow — the same flow the portal SPA runs on login. For scripted configuration, provision an account automation client instead: a client_credentials credential bound to your company account, granted the service_management capability for the routes on this page. Either way the calls act as your company user and are scoped to your company's services. See Authentication for the token mechanics.

Every /api/services/{id}/* route is owner-scoped: a service you don't own returns 404 (never a 403 that would leak its existence).

Managing services

A service is the unit a person connects to. Each has a name, an audience, a per-company share code, its own zero-knowledge keypair, plus request-field, share-field, webhook and client configuration.

The full connect handle a person uses is COMPANYCODE/SERVICECODE — your company profile share code, a slash, the service share code. See How it works → connect handles.

Request fields (what you ask for)

Request fields declare the data a person provides when they connect. They are configured as a draft + publish set: you send the whole list, the server diffs it against the live config.

Each request-field row:

{
  "id": "…",                       // omit for a new row; present to update an existing one
  "slug": "billing_email",         // optional; ^[a-z0-9_]{1,40}$, derived from the label when omitted, stable after
  "field_type": "email",           // immutable once set
  "suggested_field_id": "…",       // optional advisory: a global person|any field of the same type
  "label": "Billing email",        // optional display label
  "hint": "Where we send invoices", // optional helper text
  "mandatory_provide": true,       // hard gate — the person cannot connect without answering
  "mandatory_connected": false,    // must be a LIVE field (no share-once); implies mandatory_provide
  "one_time": false,               // a frozen snapshot; locked once values exist
  "audience": "person",            // person (default) | company | both — which customer type the row is asked of
  "verified": false,               // demand an answer from a verified field (person rows, never one_time)
  "verified_max_age_days": null    // optional: the verification may be at most this many days old
}

An example publish call:

curl -X PUT "https://api-eu.allme.fyi/api/services/$SERVICE_ID/request-fields" \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "config_token": "<from the GET>",
        "fields": [
          { "field_type": "email", "label": "Billing email", "mandatory_provide": true },
          { "field_type": "phone", "label": "Support phone" }
        ]
      }'

How the diff is applied

• Known ids update cosmetics + flags (field_type is immutable; one_time can't change once values exist).
• New rows (no id) are inserted.
• Missing ids are removed; the provided values and pending consents they held are cleaned up shortly afterwards.
• Rows added on a live service trigger a consent fan-out: one merged consent request per existing connection plus a visible push to each person, delivered in the seconds after the response. The response includes consent_requests_created.
• The config_token guards against concurrent edits: a stale token returns 409 services.config_conflict. Always GET first, send back the token you received.

Sharing back & the company profile

Share fields are what your service shares with everyone connected to it — stored as plaintext by design (so new connections see your support email, address, etc. instantly). The company profile is your company-level data, shared with every connection on any of your services.

Webhooks

Webhook endpoints are configured per service. The config is documented in detail on the Webhooks page (events, format, auth modes, the account-key envelope); here are the routes:

curl -X POST "https://api-eu.allme.fyi/api/services/$SERVICE_ID/webhooks" \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/allus/webhook",
        "events": [],          // empty = all events
        "format": "json",
        "auth_type": "hmac",   // hmac (default) | bearer | basic | header | none
        "encrypt_payload": false,
        "enabled": true
      }'
# response includes "hmac_secret_once" — capture it; it is never shown again

Registered API clients

A service's machine-to-machine credentials (used to call the service API) are managed here. Exactly one client per service.

A registered client is confidential and supports two grants: client_credentials (the default for the data API) and authorization_code + PKCE (needs a redirect URI). Its reach is fixed to the service data patterns and cannot be widened by you. The pattern list itself, the full registration model, the deny-all sentinel, and how to obtain a token are on the Authentication page. To call this portal API (the surface on this page) from automation rather than the portal login, provision an account automation client with the service_management capability.

Service activity log

Each service has an operational log (never person data) — stale-queue email alerts and 7-day purge events:

The portal renders this as the Logs tab. Webhook state transitions and config changes also appear here.

Next steps

• Portal configuration guides — the illustrated, click-by-click version of everything above.
• Service API reference — reading the data your request fields collect.
• Reference — field types, error keys, the encryption spec.
• Account automation clients — drive everything on this page from a machine-to-machine credential bound to your company account.
• Open the portal API spec ↗