Implement the API
The answers the Studio expects from an external register, and its network rules.
What to implement
| Operation | Path | Needed |
|---|---|---|
| Health check | GET /health | Always: the connection test calls it first, and the Studio calls it every 5 minutes |
| The status of one member | GET /members/status/{memberCode} | Always: every login check |
| The person data of one member | GET /members/data/{memberCode} | Always: onboarding, eligibility, member data, connection test |
| The claims of one member | GET /members/claims/{memberCode} | When the organisation filters on claims |
| Verify a member with their challenge code | POST /members/verify | When the connection has "Challenge code required" on |
| List every member | GET /members | Optional: answer 501 if you do not offer it |
The paths are appended to the base URL entered in the Studio: with the base URL https://register.pannoniqa.example/api, a login check calls https://register.pannoniqa.example/api/members/status/100001.
Answers
- JSON with status 2xx, matching the reference. Fields the Studio does not know are ignored; a known field of the wrong type makes the answer unusable.
- Not found is
404for the by-code operations. "Verify a member with their challenge code" never answers 404: it answers200withverified: false, also for an unknown member code. - Person data: wherever the Studio compares facts, a found member needs
firstName,lastNameandbirthDateinparams. Without them the Studio treats the register as unavailable, never as a pass on the member code alone. Names are compared ignoring case, accents and extra spaces (ä, ö, ü and ß count as ae, oe, ue and ss); the birth date by its first ten characters,YYYY-MM-DD. - Status:
active,inactiveorpending. The organisation's filters decide what each means, for example whether people in "SAP HR" who areinactivestill count as members. - Claims are optional facts the organisation can filter on, such as
employeeGrouporleavingDate. You may send claims of your own beyond the standard ones. - Member data: the address in
params(street,zip,city) is what a frontend may show its signed-in member. Do not send a phone: the standard has none. - The member code arrives URL-encoded as one path segment. Compare it the way your system keys people.
What the Studio makes of other answers
| Answer | The Studio treats the register as |
|---|---|
401 or 403 | Unavailable, with the credentials rejected |
501 to "List every member" | Not supporting it |
| Any other status outside 2xx | Unavailable |
| No answer within 5 seconds (1.5 seconds for member data) | Unavailable |
| A body that is not JSON, breaks the contract or is larger than 4 MB | Unavailable |
An unavailable register makes the membership check unavailable, never not_valid: onboarding waits, and members whose last valid check is less than 7 days old keep signing in on that result (the grace rule).
Request ids and the health check
x-request-id: the Studio sends a new UUID with every call, in the headerx-request-id, and records it in the register's connection log with the call's outcome and duration. Log it with each request, so your IT and the organisation can find a failed call on both sides. If your register gives a request an id of its own, answer it in anx-request-id,x-correlation-idorrequest-idheader: the Studio records that too.- Every 5 minutes the Studio calls
GET /healthon every external register whose connection has a base URL and an API key, so the register's connection health shows whether it is up even while nobody signs in. Answer it quickly, without asking slow backends, and with the same API key, tenant ID and scope as every other call. - What the connection log keeps of every call, successful or not: when, which operation, the outcome and the reason, the status, the duration and both request ids. With each call it stores its call details for 30 days: the request as the Studio sent it (method, the whole address with the member code, the headers, the body with the facts sent) and your answer (status, headers, body), each body up to 64 KB. It never stores the API key, not even as a placeholder, and masks the challenge code (
memberSecret) as***, also where your answer repeats it. Only the organisation's owners and administrators can open them, each opening is recorded, and an erasure of a member deletes the call details of their member code. Still, never repeat the challenge code or the API key in an answer.
Network rules
- HTTPS only, on a public address. The Studio refuses private and reserved addresses, and plain
httpis allowed only forlocalhostor127.0.0.1in a local test setup, never in production. - Redirects are followed only on the same origin, at most 3. A redirect to another host is refused.
- No credentials, query or fragment in the base URL.