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
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. |
|
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
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. |
|
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:
Query parameters
limit (optional)
Query Parameter —
The number of objects to retrieve on a page (2-1000). Values outside the range are set to the closest limit.
default: 50
minimum: 2
maximum: 1000
after (optional)
Query Parameter —
An offset token for fetching a specific page. Provided by the server.
Return type
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 request header;
the media type will be conveyed by the
Content-Type response header.
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. |
|
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:
Request body
Body Parameter — PSK to upload.
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the
Content-Type response header.
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 |
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
endpoint_name
String
The unique endpoint identifier that this PSK applies to. 16-64 printable (non-control) ASCII characters.
pattern: /^[ -~]{16,64}$/
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.
pattern: /^(0[xX])?[0-9a-fA-F]{32,64}$/
endpoint_name
String
The unique endpoint identifier that this PSK applies to. 16-64 printable (non-control) ASCII characters.
pattern: /^[ -~]{16,64}$/
created_at (optional)
Date
($date-time)
The date-time (RFC3339) when this PSK was uploaded to Device Management.
