SAP Open Connectors

Authenticate a Connector Instance (API)

How you authenticate a connector instance with our APIs differs significantly from connector to connector 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 connector 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 a connector 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 a connector 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 a connector 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 connector along with their source (the vendor, a Common Resource, or normalized SAP Open Connectors 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 connector 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.openconnectors.us2.ext.hana.ondemand.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 common resource that is mapped to the API provider resource identified in the vendorName attribute. For more information see Introduction to Common Resources.
    • ceCanonical indicates a normalized SAP Open Connectors 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 SAP Open Connectors mappings and call the vendor endpoint directly, while still proxied by SAP Open Connectors. In this case, name and vendorName attributes are identical.