ISAN API 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 offers two level of authentication: 

1. a basic discovery access unlocked once authenticated in the API (partial sets of data similar to the ISAN public search)
2. a full access unlocked once 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=='

Once connected to the API, users can perform basic search and basic ISAN lookups, but only limited results and data is returned (partial set of data similar to the ISAN public search). To perform more operation and access to full ISAN data sets, users need also to authenticate in the ISAN registry (see next paragraph)

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

Once connected to the ISAN API,  all functionalities linked to the user profile will be unlocked  provided that 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://web.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