Documentation

Mistake on this page? Email us

Using the APIs

This section explains how the Device Management REST APIs work in general terms. If you've never worked with a REST API before, look at this tutorial.

This overview applies to using the APIs directly. The other methods are:

There are two main ways to interact with an API:

Concepts

Requests

When you make a request using an API, HTTP provides the following methods:

  • GET: retrieve information.
  • POST: set or send new information.
  • PUT: change existing information.
  • DELETE : remove information.

There is usually a response from the server, either a block of information formatted as JSON, or a status code.

Note: Some API operations are restricted to certain account types. If you send a request that you're not authorized to use, the server responds with a 403 code.

API resources

Each API resource has at least one uniform resource identifier (URI) associated with it. The URIs follow a predictable and hierarchical structure that provides resource relations.

Device ID

To use the APIs, you must provide the Device ID, not its PSK ID. For more information, see the device identity section.

cURL requests

cURL is a utility that lets you make HTTP requests through your command line. Refer to the cURL documentation for more information on setting up and using cURL.

In our API documentation, you can see example cURL requests. The model for these requests is:

curl -X <method> https://{host}/<endpoint> \
-H 'Authorization : Bearer <api_key>' \
-H 'content-type : application/json' \
-d '{
      "name" : "Device.",
      "description" : "Testing."
}'

Replace <method> with GET, PUT, POST, or DELETE.

Authentication

Authenticate Device Management APIs using API keys, which you can obtain from Device Management Portal. For more information, see Access Device Management with API keys.

The APIs use bearer authentication:

Authorization: Bearer ak_272f4259b2b1470599c19bc4a473d3cb

You must make all requests to the APIs over HTTPS; requests made over HTTP will redirect, and requests made without an authentication mechanism will fail.

Warning: An API key has full privileges to your account, so keep it secret. The full API key is used for authorization only. Never put it in your request as part of the URI or a query parameter, as it may then be visible in network server logs. If you think your API key was compromised, contact us.

Request ID

The server assigns a unique and permanent request ID to each API request. A single request always returns the same ID:

  • In each response, in the X-Request-ID header.
  • In an error response, in the request_id field (in addition to the X-Request-ID header).

The maximum length of an ID is 32 characters.

Tip: When contacting support, please provide the request ID.

Status codes and errors

The server returns the request's success or failure information by using an HTTP status code. The status codes are grouped by type:

  • 200 range: Success.
  • 300 range: Further action is required by the caller.
  • 400 range: Errors due to request input.
  • 500 range: Errors on the Device Management servers.

Note: Specific REST API features can be restricted for any user account. The server responds with a 403 status code for requests sent to a feature that is restricted for the account.

General error codes and types

The following is a description of some general error codes. Most APIs also provide a list of specific error codes.

Code Type Description
400 bad_request Something is wrong with the request.
400 validation_error One of the parameters is invalid.
401 invalid_auth Authentication failure: provided authorization header is invalid.
401 auth_mismatch Authentication failure: provided authorization header is not allowed for this request.
401 invalid_token Authentication failure: provided token is invalid.
401 invalid_apikey Authentication failure: provided API key is invalid.
403 access_denied Authenticated user is not authorized to access the resource or execute the request.
403 access_restricted Access was blocked to comply with export control.
403 account_limit_exceeded The account limit has been reached.
403 invalid_request Trying to access using HTTP instead of HTTPS.
404 not_found Resource was not found.
404 unrecognized_request Unrecognized request URL, or method not supported by the API.
405 method_not_supported Specified method is not supported by the API.
500 internal_server_error Unexpected internal server error.

Error response model:

    "object": "error",
    "code": "<error_code>",  // HTTP status code, for example, 400.
    "type": "<error_type>",  // For example, "validation_error".
    "message": "A human-readable message with detailed info",
    "fields": [
        {
            "name": "<field_name>",
            "message": "A human-readable validation error"
        }
    ],
    "request_id": "<request_id>" // As assigned for the incoming request.
}

Pagination: Viewing results

Resources support bulk GET actions using the list operation. The list API uses common arguments. All parameters are optional.

Argument Description
limit The number of results to return. Default: 50, minimum: 2, maximum: 1000.
after The entity ID after which to start fetching.
order The order of the records to return. Available values are ASC and DESC. The default value is ASC.
has_more Indicates whether there are more results for you to fetch in the next page.
include Comma-separated additional data to return. Currently supported: total_count.

Filtering results

Filters allow you to sort returned results. Refer to the Service API references to see which operations support filtering. Define the field filter by adding a double underscore (__) to the end of the field name concatenated with the operator.

Filter operators:

Operator Usage
Equal __eq
Not equal __neq
Less or equal __lte
Greater or equal __gte
Include records __in
Exclude records __nin

An example request:

GET /v3/users?status__eq=ACTIVE

An example response:

{
    "object": "list",             // API Resource name.
    "limit": "<request_limit>",   // From request (range: 2-1000), or equal to total_count.
    "after": "<request_after>",   // Entity ID, from request or null,
                                  // For example, 2d238a89038b4ddb84699dd36a901063
    "order": "<request_order>",   // ASC or DESC. Default: ASC.
    "data": [
        // < entity >,
        // <   ...  >,
        // < entity >
    ]
}

To filter date-time fields, specify a filter value using RFC3339 (for example, 2016-11-30T16:25:12.1234Z) or a truncated format (for example, 20161130T162512Z).

Backward compatibility

To minimize the risk of breaking your integration:

  • Ignore unexpected fields from responses.
  • Don't rely on the order of fields in the responses.
  • Expect new API resources and types to emerge.