Login

What you can build

Login with the methods the library system offers: identifier and password or PIN, identifier alone, or single sign-on through an identity provider. The configuration tells the client which methods and identifier types to offer, so the login screen matches the library.

Typical flow

1. With a password or PIN, the client sends the identifier and the credential to AuthenticatePatron.
2. Without a credential, the client sends the identifier alone to AuthenticatePatronNoPassword.
3. With single sign-on, the client fetches the login URL with GetPatronAuthenticationUrl, and the patron logs in with the identity provider.
4. The provider returns code and state to CallbackPatron, and the client exchanges the code with AuthenticatePatronByCodeAndCodeVerifier.
5. Every method responds with the patron, including the patronId the other patron calls use.

What the API provides

• patron.login in GetConfiguration lists the identifierTypes, credentials and identityProviders the provider accepts.
• patron.login.credentials says whether the patron logs in with a password or a pin. The field in the request is called password either way.
• AuthenticatePatronNoPassword is only available when patron.login.allowWithoutCredential is true. The specification says it should only be used when absolutely necessary.
• Single sign-on uses PKCE: the client sends a code_challenge and a state, and later the matching code_verifier.
• When the patron does not exist but can be registered, the callback carries can_be_registered=true, and the client continues with sign-up (2.2.3).
• A failed sign-on returns error on the callback, for example sso_login_cancelled or provider_patron_not_found. For sso_access_denied and sso_consent_denied, the patron should be advised to contact their library.

What you can build

Patrons become borrowers without visiting the library: with an identifier, or through an identity provider. They choose where to pick up reservations and accept the library's consents as part of the sign-up.

Typical flow

1. With an identifier, the client checks with IsPatronRegistrationPossible that the patron can be registered.
2. The patron chooses a pick-up location and accepts the consents. The client creates the patron with RegisterPatronByIdentifier.
3. With single sign-on, the patron goes through the identity provider from GetRegisterPatronUrl. The callback CallbackPatron carries can_be_registered and the consents to accept.
4. When can_be_registered is true, the client collects the pick-up location and consents and creates the patron with RegisterPatronByCodeAndCodeVerifier. Otherwise the provider has already created the patron, and the client logs in (2.2.1).
5. The response tells how far the registration has come in status.

What the API provides

• patron.registration in GetConfiguration lists the identifier types and identity providers that can be used to register.
• status is done, in_progress or contact_the_library. When the status is done, patronId should be set; otherwise the patron logs in again.
• pickupLocation is required on both registration calls.
• The client must make sure the patron has accepted each consent in consents before the request is sent.
• Consents from the callback are formatted as type:version, URL Base64 encoded, and all of them must be included in the registration.

What you can build

Useful for a household that shares a device: each patron logs in once, and the client switches between them without logging out and in again.

Typical flow

1. Each patron logs in separately (2.2.1).
2. The client keeps the patronId of each patron who is logged in on the device.
3. When the patron switches user, the client uses the chosen patron's patronId in the calls that follow.

What the API provides

• The specification has no separate operation for several users. Switching user happens in the client.
• Removing a patron from the device happens in the client and does not change the patron's account at the library.

What you can build

Patrons get back into their account from the login screen, without contacting the library.

Typical flow

1. The patron enters their identifier and the email address registered with the library.
2. The client calls ResetPatronCredential.
3. The provider sends a reset link to that address, and the patron sets a new credential through it.
4. The patron logs in with the new credential (2.2.1).

What the API provides

• Only offer the feature when patron.credentials.resettable in GetConfiguration lists a credential. When credentials is missing, offer neither reset nor change.
• credential selects password or pin. When it is missing, the provider decides which one to reset.
• The identifier follows patron.login.identifierTypes. email is required and only selects one of the patron's addresses: the link is sent only if that address is attached to the patron and verified.
• A well-formed request always gets 202, whether a link is sent or not, so the call never reveals whether a patron exists.
• The link is the provider's. Its token must be single use and expire after a short period, and the request carries no URL.