Documentation

Mistake on this page? Email us

Certificate enrollment API

API for managing certificate renewals on devices.
Version: v3
Host: https://api.us-east-1.mbedcloud.com

Endpoints

DeviceSecurityDeviceCertificateRenewals

get /v3/certificate-enrollments/{certificate-enrollment-id}
Get a certificate enrollment by ID. Show more Show less

Get a certificate enrollment by ID.

Example:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/certificate-enrollments/01612df56f3b0a580a010fc700000000 \
-H 'Authorization: Bearer <api_key>'
Path parameters
certificate-enrollment-id (required)
Path Parameter — Certificate enrollment ID.
Return type
Example data
Content-Type: application/json
{
  "device_id" : "01625daa23230a580a0100bd00000000",
  "updated_at" : "2017-01-01T00:00:00Z",
  "enroll_result" : "success",
  "certificate_name" : "customer.dlms",
  "created_at" : "2017-01-01T00:00:00Z",
  "enroll_result_detail" : "The device is currently processing too many certificate renewals.",
  "etag" : "1",
  "enroll_status" : "new",
  "id" : "01612df56f3b0a580a010fc700000000",
  "object" : "certificate-enrollment"
}
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 OK. CertificateEnrollment
400 Validation error. ErrorObjectResponse
401 Unauthorized. ErrorObjectResponse
403 Forbidden. ErrorObjectResponse
404 Not found. ErrorObjectResponse
get /v3/certificate-enrollments
Get certificate enrollments list. Show more Show less

Get certificate enrollments list, optionally filtered.

Examples:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/certificate-enrollments \
-H 'Authorization: Bearer <api_key>'
curl -X GET https://api.us-east-1.mbedcloud.com/v3/certificate-enrollments?device_id__eq=01612df56f3b0a580a010fc700000000 \
-H 'Authorization: Bearer <api_key>'
Query parameters
device_id__eq (optional)
Query Parameter — An optional filter for the device ID.
certificate_name__eq (optional)
Query Parameter — An optional filter for a certificate.
limit (optional)
Query Parameter — The number of results to return (2-1000).
after (optional)
Query Parameter — The ID of the item after which to retrieve the next page.
order (optional)
Query Parameter — The order of results.
include (optional)
Query Parameter — a comma-separated list of data fields to return.
enroll_status__neq (optional)
Query Parameter — An optional filter for the non-equal certificate enrollment status.
enroll_status__eq (optional)
Query Parameter — An optional filter for the certificate enrollment status.
enroll_result__neq (optional)
Query Parameter — An optional filter for the non-equal certificate enrollment result.
enroll_result__eq (optional)
Query Parameter — An optional filter for the certificate enrollment result.
created_at__lte (optional)
Query Parameter — An optional filter for the date-time, less than or equal, of the certificate enrollment requests creation. Must be in RFC3339 format (for example, 2018-01-30T10:03:50.106Z). format: date-time
created_at__gte (optional)
Query Parameter — An optional filter for the date-time, greater than or equal, of the certificate enrollment requests creation. Must be in RFC3339 format (for example, 2018-01-30T10:03:50.106Z). format: date-time
updated_at__lte (optional)
Query Parameter — An optional filter for the date-time, less than or equal, of the certificate enrollment requests update. Must be in RFC3339 format (for example, 2018-01-30T10:03:50.106Z). format: date-time
updated_at__gte (optional)
Query Parameter — An optional filter for the date-time, greater than or equal, of the certificate enrollment requests update. Must be in RFC3339 format (for example, 2018-01-30T10:03:50.106Z). format: date-time
Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "device_id" : "01625daa23230a580a0100bd00000000",
    "updated_at" : "2017-01-01T00:00:00Z",
    "enroll_result" : "success",
    "certificate_name" : "customer.dlms",
    "created_at" : "2017-01-01T00:00:00Z",
    "enroll_result_detail" : "The device is currently processing too many certificate renewals.",
    "etag" : "1",
    "enroll_status" : "new",
    "id" : "01612df56f3b0a580a010fc700000000",
    "object" : "certificate-enrollment"
  } ],
  "total_count" : 6,
  "limit" : 0,
  "after" : "01625daa23230a580a0100bd00000000",
  "has_more" : true,
  "object" : "list",
  "order" : "ASC"
}
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 OK. CertificateEnrollmentListResponse
400 Validation error. ErrorObjectResponse
401 Unauthorized. ErrorObjectResponse
403 Forbidden. ErrorObjectResponse
post /v3/devices/{device-id}/certificates/{certificate-name}/renew
Request certificate renewal. Show more Show less

Request a certificate renewal.

Example:

curl -X POST https://api.us-east-1.mbedcloud.com/v3/devices/01612df56f3b0a580a010fc700000000/certificates/customer.dlms/renew \
-H 'Authorization: Bearer <api_key>' \
-H 'content-length: 0'
Path parameters
device-id (required)
Path Parameter — The device ID.
certificate-name (required)
Path Parameter — The certificate name.
Return type
Example data
Content-Type: application/json
{
  "device_id" : "01625daa23230a580a0100bd00000000",
  "updated_at" : "2017-01-01T00:00:00Z",
  "enroll_result" : "success",
  "certificate_name" : "customer.dlms",
  "created_at" : "2017-01-01T00:00:00Z",
  "enroll_result_detail" : "The device is currently processing too many certificate renewals.",
  "etag" : "1",
  "enroll_status" : "new",
  "id" : "01612df56f3b0a580a010fc700000000",
  "object" : "certificate-enrollment"
}
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 Created. CertificateEnrollment
400 Validation error: There is no certificate issuer configured for this certificate. ErrorObjectResponse
401 You are not authorized to perform the action. ErrorObjectResponse
403 Forbidden. ErrorObjectResponse
404 The device ID or certificate name is not found. ErrorObjectResponse
409 Conflict. A renewal request for this certificate is in progress. ErrorObjectResponse
423

Either:

  • Operation not supported for this device.
  • The device is not connected.
ErrorObjectResponse

Models

CertificateEnrollment

created_at
Date Creation UTC time RFC3339. format: date-time
etag
String Entity instance signature.
id
String The certificate enrollment ID.
device_id
String The device ID.
certificate_name
String The certificate name.
enroll_status (optional)
String The status of certificate enrollment request.
Enum:
new
completed
enroll_result (optional)
String The result of certificate enrollment request.
Enum:
success
failure
enroll_result_detail (optional)
String Additional information in case of failure.
updated_at (optional)
Date Update UTC time RFC3339. format: date-time
object (optional)
Enum:
certificate-enrollment

CertificateEnrollmentListResponse

object (optional)
String Describes the type of objects in the list.
Enum:
list
limit (optional)
Integer The number of results to return. format: int32
after (optional)
String The entity ID to fetch after the given one.
order (optional)
String Record order based on creation time. Acceptable values: ASC, DESC. Default: ASC.
Enum:
ASC
DESC
total_count (optional)
Integer The total number of records. format: int32
has_more (optional)
Boolean Flag indicating whether there are more results.
data (optional)
array[CertificateEnrollment] List of certificate enrollments.

ErrorObjectResponse

code
Integer Error code. Correlates with response status code. format: int32
fields
array[FieldMessageEntry] A list of request fields that failed validation.
message
String Error message.
object
String Entity name: error.
request_id
String Request ID from JWT.
type
String Error type.

FieldMessageEntry

field (optional)
String Field name.
message (optional)
String Error message related to the field.