Currently following authorization grants are supported:
Client sends its credentials (client ID + key) to security API and get access + refresh token pair back.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=client_credentials
HTTP Method
GET
POST
Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=client_credentials
JSON response returned in case of successful authentication will be in following format:
{
"access_token": "0929676d-5308-4152-8384-fdca51e1c1c2",
"expires_in": 1799,
"refresh_token": "c68c3a66-0b38-40a0-a975-4fef9f4c5844",
"token_type": "bearer"
}
Client sends its credentials along with institution email and password credentials to security API and get access + refresh token pair back.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=email_password&email=$email&password=$password
HTTP Method
GET
POST
Client sends its credentials along with institution IP address to security API and get access + refresh token pair back. If institutionId is specified, it is checked to match IP address. In case of mismatch authentication is failed.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=ip&ip=$ip_address
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=ip&ip=$ip_address&institutionId=$instituionId
HTTP Method
GET
POST
Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=ip&ip=158.152.152.121
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=ip&ip=158.152.152.121&institutionId=38
Client sends its credentials along with referrer URL to security API and get access + refresh token pair back. If institutionId is specified, it is checked to match referrer URL. In case of mismatch authentication is failed.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=referrer&referrer=$referrer_url
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=referrer&referrer=$referrer_url&institutionId=7172
HTTP Method
GET
POST
Examples
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=referrer&referrer=http%3A%2F%2Flalibcon.state.lib.la.us%2Fredirect.php%3Fillcode%3Ds1br%26database%3Dliterati
/v1/oauth/token?client_id=literati_server&client_secret=$client_secret&grant_type=referrer&referrer=http%3A%2F%2Flalibcon.state.lib.la.us%2Fredirect.php%3Fillcode%3Ds1br%26database%3Dliterati&institutionId=7172
Client sends its credentials along with institution IP address to security API and get access + refresh token pair back. Client is authenticated as nearest institution to location of specified IP address.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=geo_ip&ip=$ip_address
HTTP Method
GET
POST
Client sends its credentials along with institution ID and library card number to security API and get access + refresh token pair back. Institution ID is checked to be associated with specified library card number. In case of mismatch authentication is failed.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=libcard&libcard=$libcard&institutionId=$institutionId
HTTP Method
GET
POST
Besides getting institution object from Security API based on Shibboleth username, Security API also support following scenarios to obtain access token using Shibboleth authentication:
Returns OAuth access token based on Shibboleth username provided as parameter value in the API call. This method is used when client authenticates institution within Shibboleth by itself. To support such method, client should accept redirects back from Shibboleth and hostname where client resides should be registered within Shibboleth.
URI Path
/v1/oauth/token?client_id=$client_id&client_secret=$client_secret&grant_type=shibboleth&user=Member@testshib.org
HTTP Method
GET
POST
Checks if application key is specified correctly and returns application descriptor object. OAuth access_token should be passed as a parameter for accessing this API.
URI Path
/v1/application/auth/$app_id?key=$app_key&access_token=$access_token
HTTP Method
GET
POST
Example
/v1/application/auth/literati_server?key=$key&access_token=<access_token>
JSON response will be in following format:
{
"appId": "literati_server",
"name": "Literati",
"description": "Credo's web app for Information Literacy",
"contactName": "Nancy King",
"contactEmail": "nancy.king@credoreference.com",
"company": "Credo Reference",
"grantTypes": [],
"authorities": [
"ROLE_TRUSTED_CLIENT"
],
"dateCreated": "2012-06-06T19:08:25Z",
"lastUpdated": "2012-06-06T19:08:25Z",
"active": true,
"base": "http://alpha.api.credoreference.com"
}
Resolves institution by shibboleth user. This is internal API to be used by trusted client. Trusted client should accept redirect from Shibboleth, get shibboleth user from redirect request parameters and pass shibboleth user to API to resolve institution. OAuth access_token should be passed as a parameter for accessing this API.
URI Path
/v1/institution/shibboleth?user=$shibboleth_user&access_token=<access_token>
HTTP Method
GET
POST
Example
/v1/institution/shibboleth?user=test@bowdoin.edu&access_token=<oauth_access_token>
API services are proxied by Security Facade. To call API service client should use /v1/ prefix and add access_token parameter to URL.
URI Path
/v1/$API_URL_WITH_PARAMETERS&access_token=$oauth_access_token
HTTP Method
GET
POST
Example
/v1/search/dna?access_token=<oauth_access_token>