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

Connect and test

Entering an external register's connection in the Studio, and testing it.

Studio roles: "Owner", "Administrator", "Community manager".

Create the register

In the Studio, under "Registers", "New register" creates the register with the kind "External". The kind is fixed once the register exists. The register's groups are set once for everyone found in it.

Enter the connection

On the register's "Connection" card:

FieldWhat to enter
"Base URL"Your register's base URL. Starts with https://; plain http only for localhost or 127.0.0.1, for a local test register
"Tenant ID"Sent as the x-tenant-id header. Agree on the value with whoever runs the register
"Scope"Sent as the x-custom-scope header
"Challenge code required"On if onboarding asks for the person's challenge code; the Studio then calls "Verify a member with their challenge code"

Then "Save connection". "Tenant ID" and "Scope" take printable ASCII only, at most 255 characters each, because they are sent as HTTP headers.

The API key is set separately, with "Set API key", and later "Replace API key". It is sent as the x-api-key header, stored encrypted, and can never be shown again, only replaced. The new key takes effect at once, and the register activity records that the key changed, never the key.

Changing the scheme, host or port of the base URL removes the API key: the new address does not get the old key. Set the key again afterwards.

Test the connection

"Test connection" opens "Test the connection". Enter a "Test member code (optional)" and click "Run test". The Studio then:

  1. asks the register whether it answers (Health check);
  2. looks up the test member code, if you entered one (The person data of one member), and shows the person data returned, which it does not store;
  3. checks whether the register supports "List every member".

The card then shows the connection as "Connected" or "Unavailable", with the time of the last test. A failed test names the cause, for example:

The Studio saysUsually
"no answer within 5 seconds"The register is slow or unreachable
"the address is not allowed (private or reserved address)"The base URL resolves to a private network
"credentials rejected (HTTP 401)"The API key or tenant ID is wrong
"the answer does not match the API contract"A field has the wrong type; the paths it names show which
"found, but without person data"The answer lacks the first name, last name or birth date
"the register reports itself as unhealthy"The health check answered ok: false

Once the test passes, add the register to the membership definition. The Studio manual explains that part.