Documentation

Mistake on this page? Email us
Docs › Service API references › Service API documentation › Device Management Connect › Bootstrap API

Bootstrap API

The Bootstrap API allows web applications to control the device bootstrapping process.

See Troubleshooting the APIs for information on status and error codes.

Version: 2
Host: https://api.us-east-1.mbedcloud.com

Endpoints

PreSharedKeys

delete /v2/device-shared-keys/{endpoint_name}
Remove a PSK. Show more Show less

Remove a PSK.

Example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v2/device-shared-keys/my-endpoint-0001 \
-H "Authorization: Bearer <api_key>"
Path parameters
endpoint_name (required)
Path Parameter — The unique endpoint identifier that this PSK applies to. Reserved characters must be percent-encoded.
Responses
status description schema
204 Successfully deleted. Responds even if the endpoint does not have an associated PSK.
400 Bad request. Endpoint name validation failed. Contains error INVALID_ENDPOINT_NAME. String
401 Authentication failure.
get /v2/device-shared-keys/{endpoint_name}
Get a PSK. Show more Show less

Check if a PSK for an endpoint exists or not. The response does not contain the secret itself.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/device-shared-keys/my-endpoint-0001 \
-H "Authorization: Bearer <api_key>"
Path parameters
endpoint_name (required)
Path Parameter — The unique endpoint identifier that this PSK applies to. Reserved characters must be percent-encoded.
Return type
PreSharedKeyWithoutSecret
Example data
Content-Type: application/json
{
  "endpoint_name" : "my-endpoint-0001",
  "created_at" : "2017-07-21T17:32:28.012Z"
}
Responses
status description schema
200 Pre-shared key for the device (does not contain secret). PreSharedKeyWithoutSecret
400 Bad request. Endpoint name validation failed. Contains error INVALID_ENDPOINT_NAME. String
401 Authentication failure.
404 The PSK does not exist.
get /v2/device-shared-keys
List PSKs. Show more Show less

Retrieve pre-shared keys (PSKs) with pagination. Default page size of 50 entries.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v2/device-shared-keys \
-H "Authorization: Bearer <api_key>"
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Query parameters
limit (optional)
Query Parameter — The number of entries per page.
after (optional)
Query Parameter — An offset token for fetching a specific page. Provided by the server.
Return type
ListOfPreSharedKeysWithoutSecret
Example data
Content-Type: application/json
{
  "continuation_marker" : "001e001000120010fac8f300487f11e8839a459edde8bd42f07fffffebf07fffffebb1219cc7862b64bbaf775dc545e274810005",
  "data" : [ {
    "endpoint_name" : "my-endpoint-0001",
    "created_at" : "2017-07-21T17:32:28.012Z"
  } ],
  "limit" : 50,
  "has_more" : true,
  "after" : "001e001000120010fac8f300487f11e8839a459edde8bd42f07fffffebf07fffffebb1219cc7862b64bbaf775dc545e274810004",
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 List of PSKs. ListOfPreSharedKeysWithoutSecret
400 Bad request. Contains the error as a string, either TOKEN_NOT_FOUND or INVALID_LIMIT.
post /v2/device-shared-keys
Upload a PSK to Pelion Device Management. Show more Show less

Upload a PSK for an endpoint to allow it to bootstrap. The existing key cannot be overwritten, but needs to be deleted first in the case of re-setting a PSK for an endpoint.

Note: The PSK APIs are available only to accounts that have this feature enabled.

Example:

curl -X POST https://api.us-east-1.mbedcloud.com/v2/device-shared-keys \
-H "Authorization: Bearer <api_key>" \
-H "content-type: application/json"  \
     -d '{ "endpoint_name": "my-endpoint-0001", "secret_hex": "4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a4a" }'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json
Request body
body PreSharedKey (required)
Body Parameter — PSK to upload.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Successfully created.
400 Bad request. Contains comma-separated errors INVALID_ENDPOINT_NAME, INVALID_SECRET_HEX, and MALFORMED_JSON_CONTENT. String
401 Authentication failure.
403 Forbidden. You need to read and accept the PSK license in Device Management Portal.
409 Conflict. The PSK for the endpoint already exists and cannot be overwritten. Contains error KEY_ALREADY_EXISTS_FOR_ENDPOINT. String

Models

ListOfPreSharedKeysWithoutSecret

object
String

The type of this API object is a "list".

limit
Integer

The value of limit query parameter from the request, or default if not specified.

order
String

Record order based on creation time.

has_more
Boolean

More results are available.

after (optional)
String

An offset token for current page.

continuation_marker (optional)
String

An offset token for fetching the next page. Note that exactly the same limit needs to be used on the request for fetching subsequent pages.

data
array[PreSharedKeyWithoutSecret]

Array of the PSK entries. The array is empty if there are no PSKs.

PreSharedKey

endpoint_name
String

The unique endpoint identifier that this PSK applies to. 16-64 printable (non-control) ASCII characters.

secret_hex
String

The secret of the PSK in hexadecimal. It is not case sensitive; 4a is same as 4A, and it is allowed with or without 0x in the beginning. The minimum length of the secret is 128 bits and maximum 256 bits.

PreSharedKeyWithoutSecret

endpoint_name
String

The unique endpoint identifier that this PSK applies to. 16-64 printable (non-control) ASCII characters.

created_at (optional)
Date ($date-time)

The date-time (RFC3339) when this PSK was uploaded to Device Management.

Previous Next