General

Finna includes an API that can be used to determine whether the login credentials given by a user are correct. The API does not return patron information, only a success code.  Successful authentication does not require the user to have an account in Finna, only in the target library system.

N.B. The authentication API is only available on agreement.

Character set is always UTF-8 (composed).

Please note that this API is very limited in functionality. Finna also supports OpenID Connect that offers more robust functionality and access to user attributes.

Functions

getLoginTargets

https://api.finna.fi/api/v1/auth/getLoginTargets?<parametrit>

Returns a list of available login targets (libraries), where a login request can be made. The response also includes information whether a secondary login field (typically user's last name in addition to library card number and PIN code) is required.

Example request:

https://api.finna.fi/api/v1/auth/getLoginTargets?prettyPrint=1&lng=en-gb

Example response:

{
    "targets": [
        {
            "id": "moominvalley",
            "name": "Moominvalley library",
        },
        {
            "id": "testi",
            "name": "Test library",
            "secondary_login_field_label": "Last Name"
        }
    ]
}

libraryCardLogin

Returns whether the login was successful and any errors encountered. The parameters must be sent with a POST request (application/x-www-form-urlencoded; charset=utf-8) .

Example request (here as a GET request, use a POST request):

https://api.finna.fi/api/v1/auth/libraryCardLogin?target=moominvalley&username=100010&password=12345&secondary=Moominpappa

Example response of a successful login:

{"result":"success","status":"OK"}

Example response of a failed login (invalid user name or password):

{"result":"failure","status":"OK"}

Example response of a failure processing the request e.g. because the library backend is not available:

{"status":"ERROR","statusMessage":"Backend unavailable"}

History

20.3.2017 Initial versionTODO