Suomeksi (in Finnish): Finnan kirjautumisrajapinta

History

20.3.2017 Initial version

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.

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

Character set is always UTF-8 (composed).

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.

ParameterTypeDescripionAllowed Values
prettyPrintNumberWhether the JSON is pretty-printed with line feeds0 (default), 1
lngStringLanguage to use
  • fi (Finnish, default)
  • sv (Swedish)
  • en-gb (English)

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

ParameterTypeDescriptionAllowed Values
prettyPrintNumberWhether the JSON is pretty-printed with line feeds0 (default), 1
lngStringLanguage to use
  • fi (Finnish, default)
  • sv (Swedish)
  • en-gb (English)

targetStringLogin target, i.e. libraryAny id returned by getLoginTargets request
usernameStringUser name (library card number) 
passwordStringPassword (PIN code) 
secondaryStringSecondary identification field if getLoginTargets returned a secondary_login_field_label 

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"}