POST /instances
Create a new authenticated element instance specified by element key.
Alternatively, you can create an element instance with a POST /elements/{keyOrId}/instances request.
Create an Element Instance Request Body Parameters
The body parameters differ based on the authentication type and parameters required by each individual element. For specific requirements, see the Authenticate or Create Instance section in the documentation for a specific element. We've provided some default parameters below for our two most common authentication types, Basic and OAuth 2.0.
Basic Authentication Default Parameters
key | The element key is a unique alphanumeric identifier for the element, distinct from the element id which is numeric. |
username | The user name needed to authenticate an element instance with Basic authentication. See the Element Documentation's Setup section to identify what value at the provider is used as the username. |
password | The password needed to authenticate an element instance with Basic authentication. See the Element Documentation's Setup section to identify what value at the provider is used as the password. |
tags | User-defined tags to further identify or categorize the element instance. |
name | The display name of the authenticated element instance. |
OAuth 2.0 Authentication Default Parameters
key | The element key is a unique alphanumeric identifier for the element, distinct from the element id which is numeric. |
providerData.code | The authorization grant code returned from the API provider in an OAuth 2.0 authentication workflow. Cloud Elements uses the code to retrieve the OAuth access and refresh tokens from the endpoint. |
oauth.api.key | The API key or client ID obtained by registering your app with the provider. See the Element Documentation's Setup section to identify what value at the provider is used as the API key. |
oauth.api.secret | The API or client secret obtained by registering your app with the API provider. See the Element Documentation's Setup section to identify what value at the provider is used as the API secret. |
oauth.callback.url | The URL where the API provider returns the authorization grant code and also where a user returns after they authorize access. |
tags | User-defined tags to further identify or categorize the element instance. |
name | The display name of the authenticated element instance. |
Create an Element Instance Response Fields
The table below shows an abbreviated list of response fields.
id | The element instance id is a unique numeric identifier for the authenticated element instance. |
name | The display name of the authenticated element instance. |
createdDate | The date and time of the initial authentication of the the element instance. |
token | The element instance token returned upon authenticating an element instance. You must include the element instance token in the Authorization header of requests to the element instance. |
element | Information about the element. |
configuration | Object containing the configuration of the element. |
eventsEnabled | Indicates whether events are configured for the instance. |
user | An object containing details about the user. |
Create an Element Instance Example Request
The following example requests represent generic requests using Basic and OAuth 2.0 authentication.
Basic Authentication Example Request
curl -X POST \
https://api.cloud-elements.com/elements/api-v2/instances \
-H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
-H 'Content-Type: application/json' \
-d '{
"element": {
"key": "insightly",
},
"configuration": {
"username": "claudeelements",
"password": "password"
},
"tags": [
"Docs"
],
"name": "Element Instance Name"
}'
OAuth 2.0 Authentication Example Request
curl -X POST \
https://api.cloud-elements.com/elements/api-v2/instances \
-H 'Authorization: User zn96SWr/RjPPWztl+oQcFkT0mbKPpW7hEvPkYcRy6xM=, Organization 4c193728a11e2d03025e29992948b12c' \
-H 'Content-Type: application/json' \
-d '{
"element": {
"key": "onedrivev2",
},
"providerData":{
"code":"WCT3Ny3QRbA6HDXY "
},
"configuration":{
"oauth.api.key": "Rand0MAP1-key",
"oauth.api.secret":"fak3AP1-s3Cr3t",
"oauth.callback.url":"https://mycoolapp.com"
},
"tags":[
"Docs"
],
"name":"Element Instance Name"
}
'
Create an Element Instance Example Response
{
"id":477858,
"name":"New Element",
"createdDate":"2018-04-11T18:25:46Z",
"token":"s1GKjbAO37W1UNsBd4GI80RmUPXk/nzTPFmLKwL1Tws=",
"element":{ },
"elementId":5993,
"tags":[ ],
"provisionInteractions":[ ],
"valid":true,
"disabled":false,
"maxCacheSize":0,
"cacheTimeToLive":0,
"configuration":{ },
"eventsEnabled":false,
"traceLoggingEnabled":false,
"cachingEnabled":false,
"externalAuthentication":"none",
"user":{ }
}