Authentication

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