What is an Access Token?
A credential that can be used by an application to access an API. Access Tokens can be either an opaque string or a JSON Web Token (JWT) . They inform the API that the bearer of the token has been authorized:
- to access a particular service or services
- on behalf of a particular user (optional)
- for a particular institution
Why Access Tokens?
The Access Token model has several benefits:
- It is more efficient for clients to use than the HMAC signature pattern which requires the client to build a unique signature for every request. Only one signature has to be built to obtain the Access Token, which reduces the cryptography overhead.
- It allows clients to have a single WSKey that can request Access Tokens for different institutions, which eliminates the client's need to manage multiple WSKeys.
- Once a client obtains an Access Token, this is the only piece of information that will need to be passed to the web service in order to authenticate both the application and user. This removes the need for the client to store user identifiers after an AccessToken has been obtained.
Obtaining an Access Token
Partial scopes
Access token are not always returned with all of the scopes which the client application requested. In some cases a partial set of the requested scopes are returned. This may be due to: user lacking permissions for particular scopes; user not granting client acess to particular scopes
Obtaining Access Tokens for Different Institutions
A WSKey can be configured to allow a client to access to data associated with several institutions via Access Tokens. Using this single WSkey a client can request different Access Tokens to access the data of different libraries that are associated with its WSKey. Organization which want act on behalf of multiple libraries should include the libraries which they want access to via the WSKey Request form.
Example:
A client has a WSKey associated with three different libraries: Colgate, Keuka College and Ithaca College. The client can request an Access Token which access data on behalf of any one of these libraries by specifying the Context Institution ID. The client can also specify which institution to authenticate the user against by specifying the Authenticating Institution ID. These values are used in all of the flows for obtaining an Access Token.
Using an Access Token
All of these flows are built around the notion of authenticating to web services via an Access Token. In this model, authenticating to the web service is a two-step process. Step one: obtain an Access Token. Step two: send the Access Token as part of the web service as part of the HTTP Authorization Header.
Clients can make a request to access token enabled web services by submitting the token as a HTTP Authorization request header parameter. For example:
Authorization: Bearer tk_Yebz4BpEp9dAsghA7KpWx6dYD1OZKWBlHjqW
