Securing Your API Calls

Introduction

The security of our API calls is of utmost importance to One45. Due to the immense power that our APIs hold, we've instituted best practices for ensuring your data is safe and secure.

Authentication & Authorization

In order to understand how we're securing our API requests, let's start by defining the two cornerstones of web-based security and how we're using them in our APIs:

• Authentication - The process of identifying a given API consumer application.
  • This process takes place when your application first generates an access token using the application's given client key and secret.
• Authorization - The process of determining the permissions and restrictions given the identity of an API consumer application.
  • This process takes place on each API request by including a valid API token in the request. It is at this point rate limit policies and resource permissions are calculated before sending back a response.

Important! When we talk aboout authentication and authorization, we're referring to this only in the context of establishing a connection between your application and the One45 system. It is solely the responsibility of your application to implement it's own authentication and authorization for its own end users.

OAuth 2.0

We use the industry-standard and battle hardened OAuth 2.0 implementation (http://oauth.net/2/) to authorize all API calls. This technology is used by many companies including Google, Facebook, and Twitter. Oauth 2.0 introduces the concept of using access tokens to authorize API requests in a secure fashion. Access tokens can be thought of as short-lived 'guest passes' to our system that must be generated by our OAuth token generation API (see Table A for description). OAuth will only generate access tokens for requests that have valid client key and secret pairs. Additionally, client key and secret pairs can only be generated by your institution's designated keyholders. As an application developer, you'll have to request the keyholder to generate a client key and secret in order to access the One45 APIs.

For more information, see OAuth 2.0 documentation

Table A - OAuth Vocabulary Descriptions

Term name	Description	Generated by	Lifespan
client_key	An identifier for an external application, used for generating an access_token.	The 'Keyholder' user via API Portal's "Manage Applications" page.	Indefinite, until keyholder revokes client access
client_secret	An password associated with a client key, used in conjunction with key to generate an access_token.	The 'Keyholder' user via API Portal's "Manage Applications" page.	Indefinite, until keyholder revokes client access
access_token	A short-lived token that provides authorization to API requests it's attached to.	The "generate" API operation, using client key & secret.	4 hours*
*or until a new access_token is generated

Best Security Practices

For best security practices, we strongly recommend:

• All API calls must be made in a secure manner through use of the HTTPS protocol. Using an insecure protocol (i.e. HTTP) will compromise any sensitive data sent in the request, including your access token or client key and secret.
• Client keys and secrets as well as access tokens should be treated as passwords and stored in a secure and confidential manner.

Recommended authentication & authorization workflow

1. Your application uses its hardcoded (but secret) client key/secret to authenticate by generating an access token.
2. Your application makes note of the returned access token.
3. The access token is used by your application to authorize subsequent API requests.
4. API requests with valid access token should return success.
5. Using this access token to authorize a request after it has expired (after 4 hours) will return a 'not authorized' response.
6. At this point, the application should recognize the 'not authorized' response and try to generate a new access token with client key/secret by repeating step 1.
7. A new access token is returned, which can be used again by your application to create further API requests, which should return successfully.
8. When this new access token expires, repeat steps 5-7.

For a simplified view of the above steps, refer to the sequence diagram in Figure A.