API Access

The EmbedThis Builder API is a REST API to allow you to interact with the Builder cloud service.

The Builder API provides calls to:

• Manage Builder accounts and users
• Manage device clouds
• Manage apps
• Manage device software updates
• Manage products
• Manage access tokens

The Builder API can be used from browser-based UI apps or from utility service commands running in the cloud or on-prem.

Authentication

Requests to the Builder service are authenticated by checking an authentication token included with the request. Ioto provides two different authentication methods for two use cases:

Authentication Method	Source	Description
BuilderAPI Token	Utility	An admin service running in the cloud or on-premises
Login Access Token	Browser	A logged in user from a web browser app

For logged in users, the Builder offers Login Access Tokens that are granted when a user logs into the service. For utility service commands, the BuilderAPI Tokens provide administrative access to the service.

An authentication token must be included in the HTTP headers for Builder API requests.

API Endpoint

The Builder API endpoint is constant for all users and consists of the path:

https://api.admin.embedthis.com/api/

After this path prefix, API calls are of the form:

CONTROLLER/ACTION

For example:

https://api.admin-qa.embedthis.com/api/user/login

HTTP Methods

All HTTP API requests use the POST method for consistency and simplicity.

HTTP Request Paths

When using Authentication tokens, the request URLs are modified to include a "/tok" URL prefix before the URL path.

For example:

https://api.admin-qa.embedthis.com/api/tok/user/find

HTTP Headers

To authorize your request, include the authentication token as an Authentication HTTP header with your request. All API requests use a HTTP Content-Type of application/json for both requests and responses.

If using login access tokens, you must also include an Origin header that is set to the domain name for your device app.

For example:

Authorization: 1234567990X0C3B0ABF3CF81DZ....
Content-Type: application/json

Request Responses

Successful Responses

Successful requests will return a HTTP status code of 200 and a response body containing a JSON object with the following properties:

• data - The response data

If the response contains an array of data, the response will also contain the following properties:

• next - The next page of results
• prev - The previous page of results
• paged - Set to true if the response is paged

Errors

REST HTTP calls will return a HTTP status code of 200 for success, 403 for authentication errors, 400 for bad requests, and 500 for service errors. When a request is unsuccessful, the content type will be set to "text/plain" and the body will contain a text error message.

Example

Here is an example to issue a request from the command line using curl or the Ioto url command using a BuilderAPI token:

curl

curl -X POST https://api.admin-qa.embedthis.com/api/tok/user/get \
     -H 'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
     -H 'Content-Type: application/json' \
     -d '{"id": "ZXXXXXXXXX"}'

url

url https://api.admin-qa.embedthis.com/api/tok/user/get \
    'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
    '{id: "ZXXXXXXXXX"}'

Note: the url command is a utility command that is installed with the Ioto CLI. It can automatically sense the arguments as either headers, or body data. JSON body data can be passed as JSON5 (like JS) and can thus omit quotes on property keys and setting the Content-Type header.

Read More

• API Authentication

Ioto APIs

Controller	Description
Account	Account API
Action	Action API
Alert	Alert API
Cloud	Alert API
Dashboard	Dashboard API
Device	Device API
Issue	Product Issue API
App/Manager	App/Manager API
Metric	Metrics API
Product	Product API
Software	Software Update API
Token	Token Management API
User	User API