Skip to main content
OCLC Support

Authentication

  1. Last updated
  2. Save as PDF
Use this service to assign a unique authorization ID in Relais ILL.

This service is used to assign a unique authorization id ('aid').  

  • When using the Authentication service the library provides patron credentials.  
  • These credentials are used to look up the patron in either Relais or in the local library system using NCIP LookupUser.  
  • Once the patron information is retrieved, Relais assigns a unique authorization id ('aid'). 
  • The 'aid' is returned to the library for use in other web services, e.g. passed to Relais via OpenURL.
  • Relais uses the 'aid' in all subsequent calls in place of the patron's credentials.  The 'aid' is valid only until the patron is idle for the configured period of time.

Authentication service URL

http://HOSTNAME/portal-service/user/authentication

HTTP Method: POST

HTTP Header Content-Type: application/json

HTTP Header User-Agent: ${user-agent}

Standard http clients (browser, http client libraries etc.) will automatically include it's User-Agent value.

HTTP Request body: JSON string.

Input

Input JSON elements

Element Description
ApiKey

A library-specific API key. Contact Relais International for your API Key.

The API key may be encrypted.

Required
UserGroup

"patron"

Required.
PartnershipId

Relais D2D - the Partnership ID indicates to which consortium/group your library belongs

Relais ILL - not used

Contact Relais International for your Partnership ID.
LibrarySymbol

Your Relais library symbol. 

Required.
PatronId*

The user's patron id or barcode. If using NCIP this is the value that is used to do the NCIP Lookup User. The patron id may be encrypted.

 Caution:  For libraries that DO NOT use Relais request management. A dummy patron id is used. Please contact Relais International to set up or obtain the dummy patron id.
Surname* The user's surname. The surname may be encrypted.
UserLogin* The patron's Relais login. The login may be encrypted.
UserPassword* The user's Relais password or if using NCIP a pin that may be required when doing the NCIP Lookup User. The password or pin may be encrypted.

*One or more of these values is required depending on what authentication/authorization is to be done.  See examples below.

Input JSON template

{
  "ApiKey": "apiKey",
  "UserGroup": "patron",
  "PartnershipId": "partnershipId",  
  "LibrarySymbol": "librarySymbol",
  "PatronId": "patronId",
  "Surname": "surname",
  "UserLogin": "userLogin",
  "UserPassword": "userPassword"
} 

Input JSON examples for Relais D2D

Example 1 - after external authentication - patron's barcode provided for NCIP lookup (encryption used) 

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "PartnershipId": "test",  
  "LibrarySymbol": "OORII",
  "PatronId": "encrypted barcode"
} 

Example 2 - after external authentication - patron's barcode and pin provided for NCIP lookup (encryption used)

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "PartnershipId": "test", 
  "LibrarySymbol": "OORII",
  "PatronId": "encrypted barcode",
  "UserPassword": "encrypted pin"
}

Example 3 - after external authentication - patron's barcode and surname provided for NCIP lookup (encryption used)

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "PartnershipId": "test", 
  "LibrarySymbol": "OORII",
  "PatronId": "encrypted barcode"
  "Surname": "encrypted surname"
}

Example 4 - after external authentication - patron's barcode and surname provided for NCIP lookup (no encryption used)

{
  "ApiKey": "GYpa21ixF48ssApghf4BFTl7rwUlv4hYauRJ1WAuJfgB9eq30",
  "UserGroup": "patron",
  "PartnershipId": "test", 
  "LibrarySymbol": "OORII",
  "PatronId": "31883721"
  "Surname": "MacKeigan"
}

Input json examples for Relais ILL

Example 1 - after external authentication - patron's barcode provided for NCIP lookup (encryption used) 

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "LibrarySymbol": "OORII",
  "PatronId": "encrypted barcode"
} 

Example 2 - after external authentication - patron's barcode and surname provided for NCIP lookup (encryption used) 

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "LibrarySymbol": "OORII",
  "PatronId": "encrypted barcode",
  "Surname": "encrypted surname",
}

Example 3 - no external authentication - patron's Relais login and password provided for lookup in Relais (encryption used) 

{
  "ApiKey": "encrypted API key",
  "UserGroup": "patron",
  "LibrarySymbol": "OORII",
  "UserLogin": "encrypted Relais login",
  "UserPassword": "encrypted Relais password",
}

Example 4 - no external authentication - patron's Relais login and password provided for lookup in Relais (no encryption used) 

{
  "ApiKey": "GYpa21ixF48ssApghf4BFTl7rwUlv4hYauRJ1WAuJfgB9eq30",
  "UserGroup": "patron",
  "LibrarySymbol": "OORII",
  "UserLogin": "mylogin",
  "UserPassword": mypassword",
}

Response

Response elements

Element Description
AuthorizationId The 'aid' (authorization id) returned by the Authentication service.
LibrarySymbol Your Relais library symbol.
Iso639_2_LangCode

The patron's language, as specified in the Relais database (which may be different than the patron's browser language).

If no language is specified the default is English.
FirstName The patron's first name
LastName The patron's surname
AllowLoanAddRequest true or false
AllowCopyAddRequest true or false
AllowSelDelivLoanChange true or false
AllowSelDelivCopyChange true or false

Response example

{
  "AuthorizationId": "12knsfd987234ldfd2",
  "LibrarySymbol": "librarySymbol",
  "Iso639_2_LangCode": "ISO639_2_Code",
  "FirstName": "firstName",
  "LastName": "lastName",
  "AllowLoanAddRequest": true,
  "AllowCopyAddRequest": true,
  "AllowSelDelivLoanChange": true,
  "AllowSelDelivCopyChange": true
}

Response errors

This service may return the following error codes and messages:

Code Type Messages
PUBAN001 Public Missing parameter
PUBAN002 Public Invalid UserGroup
PUBAN003 Public

Authentication failed. [NCIP_MSG:value]. One of the following reasons may be appended:

  • invalid credentials
  • [NCIP_MSG:value]
  • invalid cipher text in ${inputParameterName}
  • unable to use encrypted ${inputParameterName} value as it is not separated by | (pipe) character.
  • unable to use encrypted ${inputParameterName} value as one of ApiKey or cipher UTC datetime is missing.
  • unable to use encrypted ${inputParameterName} value as the cipher UTC datetime (${utcCipherDatetime}) is in wrong format. Supported format for UTC datetime is yyyyMMdd HHmmss.
  • unable to use encrypted ${inputParameterName} value as cipher UTC datetime (${utcCipherDatetime}) is a future datetime compared with current UTC datetime.
  • unable to use encrypted ${inputParameterName} value as cipher UTC datetime (${utcCipherDatetime}) is more than 5 minutes old compared with current UTC datetime.
PUBAN004 Public Service is not available
PUBAN005 Public Invalid library symbol
PUBAN006 Public ILS server connection timeout error
PUBAN007 Public ILS server response timeout error
PUBAN008 Public ILS server error
PUBAN009 Public Invalid response from ILS server
PUBAN010 Public Invalid PartnershipId
PUBAN011 Public Invalid aid
PUBAN012 Public Invalid API key
PRIAN001 Private Internal authentication error occurred. [SERVICE_MSG:Value]
PRIAN002 Private Internal error. An error occurred during creating a new patron record

[NCIP_MSG:Value]: This error place holder is available only when the ILS system response includes an error message.

[SERVICE_MSG:Value]: This error place holder is available only when any SQL related error occurs.

${inputParameterName}: This placeholder is replaced by one of ApiKey, PatronId, Surname, RecordKey, UserLogin or UserPassword.

${utcCipherDatetime}: This placeholder is replaced by the Cipher UTC datetime value. 

 Note: 

[KEY:Value] is an optional error place holder. The UI may need to display the service generated data without translation, like NCIP response's error message. Therefore, the UI can parse the data easily using the token. Multiple [..] may be available, the order is not respected.

If the authorization module returns any problem object (error code and message) as a response, it will be treated as the authentication module's private (internal) error code and message. However the original authorization module's error message will be logged.

Unsuccessful responses examples

Example 1:

{
  "AuthorizationState": {
     "AuthorizationId": "RTExd5eZubHzS2zaS43P3nzr6kc1",
     "State": false
   }
}

Example 2:

{
  "ApiKeyOk": false,
  "Problem": {
      "Code": "PUBAZ006",
      "Message": "Invalid API key"
   }
}

Example 3:

{
   "Problem": {
       "Code": "PUBAN001",
        "Message": "Missing required parameter - User login is required."
    }
}