Documentation

Mistake on this page? Email us

Secure Device Access API

The Secure Device Access (SDA) API lets you request an access token and manage trust anchors.

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

Version: 1.0
Host: http://api.us-east-1.mbedcloud.com

Endpoints

SecurityAndIdentitySecureDeviceAccess

post /ace-auth/token
Get an access token to use with a device. Show more Show less

Generate a signed CWT (CBOR Web Token). The SDA Android SDK uses this API to gain access to perform actions on the devices specified in the audience (aud).
Authorized for roles: Service, ServiceAdministrator
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/ace-auth/token \
-H 'Authorization: <valid JWT>' \
-H 'content-type: application/json;charset=UTF-8' \
-d '{
  "grant_type":"client_credentials",
  "aud":["id:f90b1017e52f4c70ad92684e802c9249","ep:dev1"],
  "scope":"turn-led-on",
  "cnf":"-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ...XwIDAQAB-----END PUBLIC KEY-----"
}'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json;charset=UTF-8
Request body
body TokenRequest (required)
Body Parameter — Create access token request.
Return type
Example data
Content-Type: application/json
{
  "access_token" : "aeiou",
  "granted_until" : "2000-01-23T04:56:07.000+00:00"
}
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;charset=UTF-8
Responses
status description schema
200 A signed CWT (CBOR Web Token) access token. TokenResponse
400 Bad request. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
401 Authentication failure. The provided header is invalid or missing. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
post /v3/trust-anchors
Create a new trust anchor for the account. Show more Show less

Create a trust anchor key pair and return the public key and creation time. Each account can have one trust anchor only. This API fails if a trust anchor already exists for the account.
Authorized for roles: Service, ServiceAdministrator
Usage example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/trust-anchors \
-H 'Authorization: <valid JWT>' \
-H 'content-type: application/json;charset=UTF-8' \
-d '{
  "description": "Trust anchor for room lighting controller."
}'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json;charset=UTF-8
Request body
body CreateTrustAnchorRequest (required)
Body Parameter — Request a new trust anchor.
Return type
Example data
Content-Type: application/json
{
  "public_key" : "aeiou",
  "updated_at" : "2017-01-01T00:00:00Z",
  "fingerprint" : "aeiou",
  "description" : "aeiou",
  "created_at" : "2017-01-01T00:00:00Z",
  "etag" : "1",
  "id" : "01612df56f3b0a580a010fc700000000",
  "public_key_der" : "aeiou"
}
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;charset=UTF-8
Responses
status description schema
201 Trust anchor created. CreateTrustAnchorResponse
400 Bad request. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
401 Authentication failure. The provided header is invalid or missing. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
403 Account limit exceeded. There is already a trust anchor defined for the account. Returns the standard error object detailing the error message. ErrorResponse
delete /v3/trust-anchors/{trust_anchor_id}
Delete a trust anchor. Show more Show less

Delete the specified trust anchor. Unrecoverable.
Authorized for roles: Service, ServiceAdministrator
Usage example:

curl -X DELETE https://api.us-east-1.mbedcloud.com/v3/trust-anchors/8e0a9494cc95b750ec6c81464eb06725 \
-H 'Authorization: <valid JWT>' \
Path parameters
trust_anchor_id (required)
Path Parameter — The id of the trust anchor to be deleted
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json;charset=UTF-8
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;charset=UTF-8
Responses
status description schema
204 Trust anchor deleted.
400 Bad request. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
401 Authentication failure. The provided header is invalid or missing. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
404 The trust anchor to be deleted was not found. ErrorResponse
get /v3/trust-anchors
Get the account's trust anchor used to sign the access token. Show more Show less

Get all trust anchors that match the account ID specified in the JWT.
Authorized for roles: Service, ServiceAdministrator
Usage example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/trust-anchors \
-H 'Authorization: <valid JWT>'
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json;charset=UTF-8
Query parameters
limit (optional)
Query Parameter — Indicates how many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
minimum: 2
maximum: 1000
order (optional)
Query Parameter — Indicates how to order the entries based on when they were created. ASC by default.
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "public_key" : "aeiou",
    "updated_at" : "2017-01-01T00:00:00Z",
    "fingerprint" : "aeiou",
    "description" : "aeiou",
    "created_at" : "2017-01-01T00:00:00Z",
    "etag" : "1",
    "id" : "01612df56f3b0a580a010fc700000000",
    "public_key_der" : "aeiou"
  } ],
  "total_count" : 1,
  "limit" : 81,
  "has_more" : false,
  "after" : "01631667477600000000000100100374",
  "order" : "DESC",
  "object" : "list"
}
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;charset=UTF-8
Responses
status description schema
200 Returns the list of trust anchors associated to the account_id specified in the access token. GetTrustAnchorsResponse
400 Bad request. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
401 Authentication failure. The provided header is invalid or missing. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
put /v3/trust-anchors/{trust_anchor_id}
Update trust anchor attributes (description). Show more Show less

Updates a trust anchor description attribute.
Authorized for roles: Service, ServiceAdministrator
Usage example:

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/trust-anchors/8e0a9494cc95b750ec6c81464eb06725 \
-H 'Authorization: <valid JWT>' \
-H 'content-type: application/json;charset=UTF-8' \
-d '{
  "description": "Trust anchor for ambient light module"
}'
Path parameters
trust_anchor_id (required)
Path Parameter — The id of the trust anchor to be updated
Consumes
This API call consumes the following media types via the Content-Type request header:
  • application/json;charset=UTF-8
Request body
body UpdateTrustAnchorRequest (required)
Body Parameter — Update trust anchor request.
Return type
Example data
Content-Type: application/json
{
  "public_key" : "aeiou",
  "updated_at" : "2017-01-01T00:00:00Z",
  "fingerprint" : "aeiou",
  "description" : "aeiou",
  "created_at" : "2017-01-01T00:00:00Z",
  "etag" : "1",
  "id" : "01612df56f3b0a580a010fc700000000",
  "public_key_der" : "aeiou"
}
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;charset=UTF-8
Responses
status description schema
200 Trust anchor updated. UpdateTrustAnchorResponse
400 Bad request. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
401 Authentication failure. The provided header is invalid or missing. Returns the standard error object detailing the error message and, optionally, the invalid fields. ErrorResponse
404 The trust anchor to be updated was not found. ErrorResponse

Models

AudienceItem

Audience item, device ID or endpoint name.

CreateTrustAnchorRequest

description
String ($Free text)

maxLength: 256

minLength: 1

The description of the new trust anchor key pair.

CreateTrustAnchorResponse

fingerprint (optional)
byte[] ($byte)

The SHA256 of the trust anchor public key; the prefix 'mbed.ta.' followed by the trust anchor public key as a SHA256 hash in Base64-encoded DER format.

public_key_der (optional)
byte[] ($byte)

The generated trust anchor public key in Base64-encoded DER format.

public_key (optional)
byte[] ($byte)

The generated trust anchor public key in PEM format.

description (optional)
String ($free text)

maxLength: 256

minLength: 1

Notes about the trust anchor.

etag (optional)
String

Entity instance signature, 1 or Unix timestamp of last customer update.

updated_at (optional)
Date ($date-time)

Update UTC time.

created_at (optional)
Date ($date-time)

Creation UTC time.

id (optional)
String

The ID of the entity.

ErrorResponse

This object represents an error message.
object (optional)
String

Entity name, always 'error'.

code (optional)
Integer ($int32)

Response code.

type (optional)
String

Error type.

Enum:
success
created
accepted
permanently_deleted
validation_error
invalid_token
invalid_apikey
reauth_required
access_denied
account_limit_exceeded
not_found
method_not_supported
not_acceptable
duplicate
precondition_failed
unsupported_media_type
rate_limit_exceeded
internal_server_error
system_unavailable
message (optional)
String

A human-readable message with detailed information.

request_id (optional)
String

Request ID.

fields (optional)
array[Field]

Input fields that failed during request object validation.

Field

name
String

Name of the erroneous field.

message
String

Message describing the erroneous situation.

GetTrustAnchorsResponse

data (optional)
array[TrustAnchorResponse]

The list of trust anchors of the account.

total_count (optional)
Integer ($integer)

order (optional)
String

Indicates how to order the entries based on when they were created.

Enum:
ASC
DESC
limit (optional)
Integer

Indicates how many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.

has_more (optional)
Boolean

Indicates whether additional results are available.

after (optional)
String

An offset token for the current page.

object (optional)
String

The type of this API object is a list.

KeyValue

TokenRequest

grant_type
String

Hardcoded - can only be "client_credentials".

aud
array[AudienceItem]

Array of <type>:<identity> tuples representing devices for which access is being requested. There must be at least one id/ep tuple.
<type> ::= id|ep
<identity>::=[a-zA-Z0-9+/=- ]+
<audience> :== <type> ":" <identity>
<identity> can be up to 60 characters long, and can contain spaces.
The audience array can contain up to 50 tuples. If IAM does not authorize even one item in the list, Secure Device Access does not authorize the whole request and does not return an access token (access denied).

scope
String ($scope-item scope-item ...)

The space-delimited list of operations that user is requesting permission for. The array must contain at least one scope item. A scope item can have up to 60 characters. A scope list can hold up to 20 scope items.
<scope>::=[a-zA-Z][a-zA-Z0-9-]*
<scope-list>::= <scope> | <scope> " " | <scope> " " <scope-list>
The scope being requested must match the action that the Android application eventually performs on the IoT device. The device matches the scope in the access token to the action requested in the operation bundle.

cnf
String ($The public key in PEM format.)

The Android application proof-of-possession public key.

TokenResponse

granted_until (optional)
Date ($date-time)

Grant expiration UTC time RFC3339.

access_token (optional)
byte[] ($byte)

The generated CWT (CBOR Web Token) access token as a Base64 string.

TrustAnchorResponse

fingerprint (optional)
byte[] ($byte)

The SHA256 of the trust anchor public key; the prefix 'mbed.ta.' followed by the trust anchor public key as a SHA256 hash in Base64-encoded DER format.

public_key_der (optional)
byte[] ($byte)

The generated trust anchor public key in Base64-encoded DER format.

public_key (optional)
byte[] ($byte)

The trust anchor public key in PEM format.

description (optional)
String ($free text)

maxLength: 256

minLength: 1

The updated notes about the trust anchor.

etag (optional)
String

Entity instance signature, 1 or Unix timestamp of last customer update.

updated_at (optional)
Date ($date-time)

Update UTC time.

created_at (optional)
Date ($date-time)

Creation UTC time.

id (optional)
String

The ID of the entity.

UpdateTrustAnchorRequest

description
String ($free text)

maxLength: 256

minLength: 1

The new description for the trust anchor.

UpdateTrustAnchorResponse

fingerprint (optional)
byte[] ($byte)

The SHA256 of the trust anchor public key; the prefix 'mbed.ta.' followed by the trust anchor public key as a SHA256 hash in Base64-encoded DER format.

public_key_der (optional)
byte[] ($byte)

The generated trust anchor public key in Base64-encoded DER format.

public_key (optional)
byte[] ($byte)

The trust anchor public key in PEM format.

description (optional)
String ($free text)

maxLength: 256

minLength: 1

The updated notes about the trust anchor.

id (optional)
String

The ID of the entity.

created_at (optional)
Date ($date-time)

Creation UTC time.

updated_at (optional)
Date ($date-time)

Update UTC time.

etag (optional)
String

Entity instance signature, 1 or Unix timestamp of last customer update.