Authentication
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
Elemento | Descrizione |
---|---|
ApiKey |
A library specific API key. Contact Relais International for your API Key. The API key may be encrypted. Richiesto |
UserGroup |
"patron" Richiesto. |
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. Richiesto. |
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
Elemento | Descrizione |
---|---|
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:
Codice | Tipo | Messages |
---|---|---|
PUBAN001 | Pubblico | Missing parameter |
PUBAN002 | Pubblico | Invalid UserGroup |
PUBAN003 | Pubblico |
Authentication failed. [NCIP_MSG:value]. One of the following reasons may be appended:
|
PUBAN004 | Pubblico | Service is not available |
PUBAN005 | Pubblico | Invalid library symbol |
PUBAN006 | Pubblico | ILS server connection timeout error |
PUBAN007 | Pubblico | ILS server response timeout error |
PUBAN008 | Pubblico | ILS server error |
PUBAN009 | Pubblico | Invalid response from ILS server |
PUBAN010 | Pubblico | Invalid PartnershipId |
PUBAN011 | Pubblico | Invalid aid |
PUBAN012 | Pubblico | Invalid API key |
PRIAN001 | Privato | Internal authentication error occurred. [SERVICE_MSG:Value] |
PRIAN002 | Privato | Internal error. 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 places holder is available only when any SQL related error is occurred.
${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.
Nota:
[KEY:Value] is an optional error placeholder. 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, order is not respected.
If the authorization module returns any problem object (error code and message) as response, it will be treated as authentication module's private (internal) error code and message. However the original authorization module's error message will be logged.
Unsuccessful responses examples
Esempio 1:
{
"AuthorizationState": {
"AuthorizationId": "RTExd5eZubHzS2zaS43P3nzr6kc1",
"State": false
}
}
Esempio 2:
{
"ApiKeyOk": false,
"Problem": {
"Code": "PUBAZ006",
"Message": "Invalid API key"
}
}
Example 3:
{
"Problem": {
"Code": "PUBAN001",
"Message": "Missing required parameter - User login is required."
}
}