Authentication

View as Markdown The page’s .md file llms.txt All pages, for AI tools Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

How a vendor gets access to the provider. The vendor exchanges its client credentials for a bearer token, sends that token on every other request, and can revoke it when it is no longer needed. This is about the vendor, not about patrons.

2 operations

POST /authentication/oauth2/revoke

Revoke access token

No authentication RevokeToken

Revoke an access token.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/authentication/oauth2/revoke" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=nordby-vendor-app' \
  --data-urlencode 'client_secret=9f2kQ7xLm4Vb8RtZ' \
  --data-urlencode 'token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MDIxODg3MyJ9.c2lnbmF0dXJl'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/authentication/oauth2/revoke`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    "client_id": "nordby-vendor-app",
    "client_secret": "9f2kQ7xLm4Vb8RtZ",
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MDIxODg3MyJ9.c2lnbmF0dXJl",
  }),
});

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/authentication/oauth2/revoke",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded",
    },
    data={
        "client_id": "nordby-vendor-app",
        "client_secret": "9f2kQ7xLm4Vb8RtZ",
        "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MDIxODg3MyJ9.c2lnbmF0dXJl",
    },
)
response.raise_for_status()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL.

Request body

application/x-www-form-urlencoded · optional · RevokeTokenRequestBody

The token that we want to revoke.

client_idstringrequired
client_secretstringrequired
tokenstringrequired
The token that we want to revoke. This is always an access_token.

Responses

200 Token was successfully revoked, or the token was invalid (i.e. it was already 'revoked').

No response body.

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

POST /authentication/oauth2/token

Authenticate client

No authentication AuthenticateClient

Authenticate the client to obtain a token.

It is recommended that the returned token is a JWT as this can come in handy if any part of the API, e.g. the search API, needs to be delegated to a third party.
The JWT could be used to ensure that only authorized clients have access to the third party API.

Example request

cURL

curl -X POST "$PLAS_BASE_URL/authentication/oauth2/token" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=nordby-vendor-app' \
  --data-urlencode 'client_secret=9f2kQ7xLm4Vb8RtZ' \
  --data-urlencode 'grant_type=client_credentials'

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/authentication/oauth2/token`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    "client_id": "nordby-vendor-app",
    "client_secret": "9f2kQ7xLm4Vb8RtZ",
    "grant_type": "client_credentials",
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"{os.environ['PLAS_BASE_URL']}/authentication/oauth2/token",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded",
    },
    data={
        "client_id": "nordby-vendor-app",
        "client_secret": "9f2kQ7xLm4Vb8RtZ",
        "grant_type": "client_credentials",
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL.

Request body

application/x-www-form-urlencoded · optional · AuthenticationClientCredentialsRequestBody

The authentication client credentials.

client_idstringrequired
client_secretstringrequired
grant_typestringrequired
One of: client_credentials

Responses

200 Success AuthenticationClientResponseBody

Generated from the schema

Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MDIxODg3MyJ9.c2lnbmF0dXJl",
  "expires_in": 1,
  "token_type": "Bearer"
}

Schema

AuthenticationClientResponseBody

access_tokenstringrequired
The access token string, as issued by the authorization server. It is strongly recommended that this token be a JWT so that it can be validated by a business partner, if e.g. the search API is delegated.
expires_inintegerrequired
The duration (in seconds) of time the access token is granted for.
token_typestringrequired
The type of the token.
One of: Bearer

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron identifier, password or pin code
  - 100011: New password or pin code rejected, because it does not meet the provider's requirements
  - 100013: The provider does not let the patron change the given credential
  - 100023: Patron ID not found
  - 100101: Patron could not be deleted, because the patron has something unresolved issue with the library (this could be anything from a loan to a fee, and so on ...)
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 10001 · 71001 · 100001 · 100011 · 100013 · 100023 · 100101 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Unauthorized login.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.