ISAN API 3.0 - authentication

Credentials are required to access the ISAN API, such credentials are delivered by ISAN-IA after signature of the ISAN supporters agreement. The profile of the user account defines the operations that are permitted when using the API; there are two profiles (to date) :

• reader users are allowed to search the ISAN Registry and perform ISAN lookups
• registrant users are allowed to register work or versions with ISAN and perform search & lookups like reader users.

Note that the ISAN API has two levels of authentication: 

1. unlock the access to the API when authenticated in the API 
2. unlock the access to the ISAN Registry when authenticated in the ISAN Registry 

the use of API3.0 requires to be authenticated in the API + authenticated in the ISAN Registry

This article covers the following topics:

1. API authentication: Authorization header
2. ISAN Registry authentication: X-ISAN-Authorization header
3. User delegation: perform operations on-behalf of another user

1. API authentication: Authorization header

The ISAN API uses the HTTP Basic authentication method.

The required HTTP Authorization header shall have the following form:

 header 'Authorization: Basic apiSignatureValue' 

Where apiSignatureValue is obtained by encoding in base 64 the api_username and api_password as follows: apiSignatureValue = Base64 (api_username:api_password) 

api_usernames and api_passwords are case sensitive.

Example:

• api_username =myApiLogin.api
• api_password = myApiPassword
• apiSignatureValue = Base64(myApiLogin.api:myApiPassword)

header 'Authorization: Basic bXlBcGlMb2dpbi5hcGk6bXlBcGlQYXNzd29yZA=='

2. ISAN Registry authentication : X-ISAN-Authorization header

After being connected to the ISAN API,  all functionalities linked to the user profile will be unlocked  once the user is also authenticated in the ISAN Registry. To do so, the X-ISAN-Authorization key need to be added to the Header of all API requests.
The X-ISAN-Authorization key is computed with the help of the ISAN user interface credentials (http://sandbox.isan.org/) obtained by the user's ISAN registration agency.

The X-ISAN-Authorization header shall have the following form:

header 'X-ISAN-Authorization: ISANUSER isanSignatureValue'

Where isanSignatureValue is obtained by encoding in base 64 the isan_username and the MD5 encoded value of isan_password, as follows: isanSignatureValue = Base64( isan_username:MD5(isan_password))

isan_usernames and isan_passwords are case sensitive.

Example:

• isan_username =myRegistryLogin
• isan_password = myRegistryPassword
• isanSignatureValue = Base64(myRegistryLogin:MD5(myRegistryPassword))

header 'X-ISAN-Authorization: ISANUSER bXlSZWdpc3RyeUxvZ2luOmM2ZDM4MGVlODVlYjUzMGY3NTQzOTdjNTlmNGNlYWEy'

Example of header with both authentications keys

 header 'authorization: Basic bXlBcGlMb2dpbi5hcGk6bXlBcGlQYXNzd29yZA==' 
 header 'x-isan-authorization: ISANUSER bXlSZWdpc3RyeUxvZ2luOmM2ZDM4MGVlODVlYjUzMGY3NTQzOTdjNTlmNGNlYWEy'
 header 'accept: application/json' 
 header 'content-type: application/json'

3. User delegation: perform operations on-behalf of another user

A registration agency administrator can log on behalf of a user of his agency to perform all operations allowed for this user profile (search, lookup, registrations, update,...)

To implement user delegation in the ISAN API, the XISAN-Authorization header need to be encoded with registration agency administrator credentials (RA admin) and the delegate user login. The syntax is the following :

• ra_login = registration agency administrator account login (e.g. myRaAccount)
• ra_pwd  =  registration agency administrator account password 
• user_login  = the delegate user account login (e.g. delegUser.update)

Note that the Authorization header remain unchanged

• api_login = the API access login (e.g. myacount.api)
• api_pwd = the API access password