Documentation/Developers
Back
  • Getting started
    • Frontends and app types
    • Environments and endpoints
  • OAuth clients
    • Client ID and secret
    • Redirect URIs and start URL
    • Secret rotation
  • Login with appsolut
    • Authorization code flow
    • Tokens and claims
    • Frontend role
    • Sign-out
    • Revocation and issued tokens
    • Token endpoint errors
  • Frontend keys
    • Issue and store a key
    • Send a key
    • Rotate and revoke
  • Members API
    • Eligibility from a backend
    • The signed-in member
    • Results, rate limits and errors
    • Is an applicant an eligible member?
    • The signed-in frontend user's membership
  • appsolut register API
    • Implement the API
    • Connect and test
    • Verify a member with their challenge code
    • List every member
    • The status of several members
    • The status of one member
    • The person data of several members
    • The person data of one member
    • The claims of several members
    • The claims of one member
    • Health check

Implement the API

The answers the Studio expects from an external register, and its network rules.

What to implement

OperationPathNeeded
Health checkGET /healthAlways: the connection test calls it first
The status of one memberGET /members/status/{memberCode}Always: every login check
The person data of one memberGET /members/data/{memberCode}Always: onboarding, eligibility, member data, connection test
The claims of one memberGET /members/claims/{memberCode}When the organisation filters on claims
Verify a member with their challenge codePOST /members/verifyWhen the connection has "Challenge code required" on
List every memberGET /membersOptional: 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 404 for the by-code operations. "Verify a member with their challenge code" never answers 404: it answers 200 with verified: false, also for an unknown member code.
  • Person data: wherever the Studio compares facts, a found member needs firstName, lastName and birthDate in params. 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, inactive or pending. The organisation's filters decide what each means, for example whether people in "SAP HR" who are inactive still count as members.
  • Claims are optional facts the organisation can filter on, such as employeeGroup or leavingDate. 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

AnswerThe Studio treats the register as
401 or 403Unavailable, with the credentials rejected
501 to "List every member"Not supporting it
Any other status outside 2xxUnavailable
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 MBUnavailable

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

Network rules

  • HTTPS only, on a public address. The Studio refuses private and reserved addresses, and plain http is allowed only for localhost or 127.0.0.1 in 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.