How to Use Cloud Elements Authentication APIs

The first milestone in building an integration is authorizing your endpoints to connect and share data, fondly called authentication. The standards for authentication often vary, and with Cloud Elements 2.0 we can support nearly all types of authentication and, furthermore, expose those APIs as simple, REST endpoints. Our Customer Enablement Manager, Clayton Shaver, recently demoed the full functionality of authentication. If you prefer to read (hey, no judgment here!) we have you covered.

Image: Duo Security (MIT News article).

Let's Start With Product Definitions

Within Cloud Elements 2.0, we have a few product definitions that are central to our platform: Elements, Instances, and Hubs. Starting with Elements, an Element is what we consider our standardized wrapper that works like an enhanced connector to an API. Our Elements Catalog, which is a listing of all the Elements that we have within our platform, contains over 120+ Elements.

The second definition that we have, is what we call an Instance. An Instance is an authenticated connection between Cloud Elements and an account at an API vendor (e.g. Salesforce or Act-On).

Our third definition is an API Hub. At the bottom of each of these Element cards, you'll see a little bubble denoting which Hub (or category) an endpoint is in, such as CRM or marketing. A Hub is a collection or folder of similar-functioning Elements within our catalog. For example, if I search on the CRM Hub here, we can see all the Elements that exist within our CRM Hub. Beyond just being a collection of similar-functioning Elements, we also standardize API calls across the Hub as well.

WATCH THE CLOUD ELEMENTS 2.0 WEBINAR: HOW TO INTEGRATE & AUTHENTICATE

A good example of this, sticking with the CRM Hub example, is that almost every CRM system has some concept of a contact, although different systems will refer to them differently. HubSpot, for example, refers to a contact as a lowercase plural contacts, whereas Salesforce refers to it as a uppercase Contact, not plural. So, we actually take that naming convention, and standardize it across all the endpoints. That way, you can get the contacts out of every single Element in the CRM Hub using just a standard, single name.

Authenticating an Element Instance With Salesforce Example

When you hover over the card, you'll see that there's a couple options: authenticate, API docs, export and my resources. When you're ready to hit "authenticate," the first screen you will see is:

From here, you can do a couple things. One, you can give it a name or provide some configuration. In this case, all the configuration for Salesforce is optional. You can also provide Element Instance Tags here. Element Instance Tags are just a way of tagging your instance so you can better search, sort and filter with these tags. We always recommend using them when you're working with Element Instances.

Once you click the create instance button, you will walk through the basic OAuth2 workflow.

A Look at How Oauth2 Works

Salesforce is an OAuth2 Element, and will take you through the through the OAuth flow. You'll log into your specific Salesforce account, where you will be presented with a permission screen. On the permission screen, you will notice that Cloud Elements Production is asking for access to your accounts.

Once you're logged in, and have successfully created an Instance, you're going to come back to the Cloud Elements Integration UI.

From here, you can do a few things. One of the best places to start is to actually look at the API docs for the Element you just created. The great thing about these interactive API docs is you can actually use these to start making calls against that Element Instance that you just created.

For instance, below is a look at that contacts from Saleforce Sales Cloud, to align with the example we've been using. Scroll down here and find that object: /contacts.

What you can do here, is pull down the /contacts endpoint and you can actually use the Try It Out button to start making calls against it.

You'll see a list of all the contacts in your Salesforce accounts being returned here. The curl call that we've used in order to actually pull the contacts from this Salesforce account is also available in the response. Let's start by looking at the path here.

All calls made against Cloud Element will use the same URL presented here in the Curl response, notice that the standard path is /hubs/CRM/contacts. Nowhere in here are we referencing Salesforce as part of our path. The only thing that we're referencing here is that CRM Hub and contacts object. So if you think about that through the lens of standardization across the Hub, you can use the same call to pull contacts from any Element inside the CRM Hub that has a contacts resource available.

User and Organization Tokens

You may be thinking "Well, how am I actually routing this call to the appropriate endpoint I just set up?" You'll see here what you do is pass in an authorization header with three parts, each part is composed of a keyword and a token.

The first two, the user and the organization, are specific to your Cloud Elements organization, and the Cloud Elements user that you're currently logged in as. The next token routes your call against the Element instance you just created. So this token is specific to that element instance that you just created, and also authorizes you to make a call against that instance.

To bring it full-circle in order to start pulling contacts from different CRM systems, the only thing that you would need to change is the Element Token in order to make calls against different endpoints. So you can start to see that velocity of building integrations begins to pick up here.