By Mark Geene in GET/technical Posted Oct 1, 2014

Step 2: Authentication [Blog Series]

5 Key Considerations for Authentications

An important step in API integrations is securely authenticating to the cloud service endpoints that connect with your app. The best API integrations don’t just happen to work. The best API integrations create a cooperative experience between apps and other cloud services. In this step, you’ll need to determine the type of authentication mechanism used by the endpoint and the workflow required.


5 Keys to Building API Integrations

Before we dive in, have you considered what cloud services need to be connected to your application to optimize user experience [STEP 1] and defined integration user stories [PRE-WORK]? 

If so, you’re now ready for the second step in the series, and to answer:Creating cooperative apps

  • How can authentication be managed at each endpoint individual users are connecting to?
  • What are the types of authentication mechanisms available to use?
  • Will cloud integrations compromise security?
  • Where should all the data for logins, passwords, keys and refresh keys be stored?

The goal for this series: Create THE Ultimate Cooperative App. This ultimate app has a simple user interface (UI) that allows users to opt into the cloud services most relevant to them. Once a user is presented with the UI to select the endpoint they wish to connect to, your application will open an authentication screen (either a pop-up window, new tab, or module). Users will use their own login credentials to access the service and grant access to connect the apps.



There are three types of authentication mechanisms you can use to connect your app to a cloud service endpoint. The authentication mechanism drives the workflow for each instance an endpoint connects to your app. For example, each time an end user in on your application and selects Dropbox to connect to. When the user is presented with an authentication screen between your app and Dropbox, that’s counted as one instance.

3 primary types of authentication used at open API endpoints:

  • OAuth – An Open Protocol that provides a process for end-users to authorize third-party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections. Credential tokens are long lived, typically a year.
  • OAuth 2 – Delegates security to the HTTPS protocol. OAuth 1 does not require this and uses alternative methods to remain secure. It also introduced the use of refresh tokens that allow authentications to expire, unless “refreshed” on a periodic basis.
  • SAML – An XML-based open standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider. SAML is popular with large single sign on organizations, corporate applications and in many older applications.

The workflows are different for each authentication method and your application. See a related post on Using OAuth with Service Endpoints.


How long do you need to keep the session active between your application and the endpoint? Is your user doing a one-time connection to the endpoint (e.g., uploading files from Box) or is this an on-going interaction between your app and the endpoint (e.g, synchronizing accounts and contacts with

If you want your user to authenticate once and then not have to authenticate again as they interact with the endpoint, your application will need to manage the refresh token from the endpoint (if available) in addition to the initial access token. Some access tokens expire in an hour, while others may last as long a a year or never expire. (See a related blog for details on the duration of cloud storage refresh tokens).

QUICK TIP: OAuth 2 is the only mechanism that has refresh tokens. This allows you to keep the token alive, so that users do not have to log in again. SAML does not use refresh tokens. Services like Xero, Quickbooks, etc. do not yet support OAuth 2.0.

Refresh tokens have similar variations in how long they are authorized for access. You will need to develop a strategy for managing access and refresh tokens for each endpoint that you connect to in order to provide a seamless user experience for your clients.


Tokens are storing very private user information. As a developer for the integration between your application and an endpoint, it’s your responsibility to protect this type of sensitive information. Some believe that OAuth is unbreakable. For argument's sake, let’s say it is, and that you’re best option to securely store tokens is with a higher bit of encryption.

If your application stores tokens it is highly recommended that you encrypt with 256 bit encryption at rest within your data storage system with the key owned by the end user. Encrypted tokens stored with 256 bit encryptions are really tough to break, protecting your application and your customers usernames and passwords.


Managing permissions from an endpoint all depends on how that endpoint is structure. Microsoft has the permissions built in. Some endpoints (like Box) will allow you to add permissions to each individual end-user account from a central admin. Permissions are attached to the file to ensure compliance.

Other solutions require validation via Active Directory (Sharepoint) or other directory services before allowing you to connect. The permissions check adds an added layer of complexity that need testing to make sure API transactions can access the data they need.

As you’re designing your API integration, consider whether or not your client will be authenticating an administrator account or an end-user account. How will you handle and pass permissions from the endpoint? An admin account at the endpoint will allow you to manage objects and data across your organization, while protecting client data with specified user’s permissions.


For support, monitoring and security purposes track the API call activity for each authenticated instance of an endpoint. When you embed integrations into your application your customers will expect you to support the integration. Your support team will need access to API call activity logs, error reports and alerts to provide the success experience for your customers. Tagging the API calls with an identifier for each customer’s instance of an integration will make it easier for your team to manage and support the specific user.

The more prepared you are in entering this new era of “Cooperative Apps” the more leverage you will have on innovative product development. Next in series, [STEP 3] Discover Standard Objects and data fields, (e.g. data structure, field names and formats) that need to be mapped into your application. Need help creating a killer cooperative app? Try Cloud Elements.

Like this blog? Explore our definitive guide to api integration to see all the information in one place.


Read Step 1: User Stories    Read Step 3: Use Discovery APIs