Authenticate an Element Instance (API)

How you authenticate an element instance with our APIs differs significantly from element to element based on the API provider's authentication requirements (OAuth 2.0, basic, OAuth 1.0, or custom) and any specific information that they require. However, the payload that you send always includes basic information including the name of the element instance, a configuration array to pass required information to the provider, tags to help you categorize the instance, and an optional request to retrieve details about the objects retrieveObjectsAfterInstantiation (see more on this below).

You can authenticate an element instance withe either of the following endpoints:

• POST /instances
• POST /elements/{id}/instances (do not include "key": "Element Key" in the body of the request).

Here is an example payload to authenticate an element instance with OAuth 2.0 authentication:

 {  
  "element":{  
    "key":"<Element Key>"
  },
  "providerData":{  
    "code":"<Authorization Grant Code>"
  },
  "configuration":{  
    "oauth.api.key": "<OAuth app API or Client Key>",
    "oauth.api.secret":"<OAuth app API or Client Secret>",
    "oauth.callback.url":"<Callback URL>"
  },
  "tags":[  
    "Tag Name 1",
    "Tag Name 2"
  ],
  "name":"Instance Name",
  "retrieveObjectsAfterInstantiation": true
}

Here is an example payload to authenticate an element instance with basic authentication

{
  "element": {
    "key": "<Element Key>"
  },
  "configuration": {
    "username": "<User Name>",
    "password": "<Password>"
  },
  "tags": [
    "Tag Name 1",
    "Tag Name 2"
	],
  "name": "<Instance Name>",
  "retrieveObjectsAfterInstantiation": true
}

Include Objects in the Response

You can return a list of all data objects in an element along with their source (the vendor, a Virtual Data Resource, or normalized Cloud Elements object). In the request body include the optional "retrieveObjectsAfterInstantiation": true value. The response includes an objects array like this example:

  "objects": [
    {
        "name": "incidents",
        "vendorName": "Case",
        "type": "ceCanonical"
    },
    {
        "name": "Task",
        "vendorName": "Task",
        "type": "vendor"
    },
    {
        "name": "myAccounts",
        "vendorName": "Account",
        "type": "vdr"
    }
  ]

The objects list includes:

• name The name of the element object.  This is name that you'll find in the API docs and endpoints. For example, requests to the objects in the example would look like GET https://api.cloud-elements.com/elements/api-v2/incidents (or /Task or /myAccounts).
• vendorName The name of the object specified within the API provider's system. 
• type Specifies where the object is defined:
  • vdr indicates that the object is a user-defined virtual data resource that is mapped to the API provider resource identified in the vendorName attribute. For more information see Introduction to Virtual Data Resources.
  • ceCanonical indicates a normalized Cloud Elements object associated with the raw API provider object identified in the vendorName attribute.
  • vendor indicates that the object is available to use via the GET /{objectName} endpoint. Requests bypass any Cloud Elements mappings and call the vendor endpoint directly, while still proxied by Cloud Elements. In this case, name and vendorName attributes are identical.