Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Overview

The IEE802.1AR standard defines unique per-device identifiers (DevIDs) and the management and cryptographic binding of a device to its identifiers. It also describes the relationship between an initially installed identity and subsequent locally significant identities, as well as interfaces and techniques for using DevIDs with both old and new provisioning and authentication protocols. Additionally, IEEE802.1AR addresses the management and use of a single IDevID (IDevID, an Initial Device Identifier), as well as numerous LDevIDs certificates (LDevID, a subsequent Locally Significant Device Identifier derived from the IDevID). It is impossible to transfer LDevIDs to a device with a different IDevID without knowing the private key that was used to modify the cryptographic binding. A provisioning server allows the Manufacturer of the Device (made during manufacturing) to control IDevIDs (also known as birth certificates) and the End User (often created during commissioning or at any time as defined by Manufacturer) to control LDevIDs.

In order to handle the DC1 adoption to the automation solution, the CM API's V2 version is introduced. Request payloads should now include information about the device in order to revoke the certificate.

Playground for Certificate Manager is available here.

# Certificate Manager API

# Keys

# PUT /keys/digicertMPKI

  • Parameters-No Parameters needed.
  • Updates the Digicert MPKI Key (PKI Admin)

Request body example

{ 
  "key": "string" 
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# DC1

# PUT /keys/digicertDC1

  • Parameters-No Parameters needed.
  • Updates the DC1 API Key (PKI Admin)

Request body example

{ 
  "key": "string" 
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# Certificate profiles

# GET /profiles

  • List all profiles (PKI Admin, Production Admin)
  • Parameters-No parameters needed.

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# POST /profiles

MPKI

  • Creates MPKI certificate profile (PKI Admin)
  • Parameters-No parameters needed.

Request body example

{
  "name": "abc",
  "configuration": {
    "EnrollmentMethod": "SCEP",
    "CertificateType": "LDEVID",
    "CAVendor": "DigiCert",
    "CAPlatform": "MPKI",
    "PlatformVersion": "v1",
    "additionalAttributes": {
      "vendorSpecificProfileAttributes": {
        "MPKI": {
          "subaccountName": "test",
          "oid": "2.16.840.1.113733.1.16.1.3.1.4.1.183527368"
        }
      }
    }
  },
  "productionUserIds": [
    "edd15e59-7dc2-45e2-a7a8-9992e1690cf7"
  ],
  "revocationUserIds": [
    "ec7c18b2-39dd-49e9-a87a-dd699080228b"
  ]
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

DC1

  • Creates DC1 certificate profile (Production Admin)
  • Parameters-No parameters needed.

Request body example

{
 "name": "Test3000",
 "configuration": {
   "enrollmentMethod": "API",
   "certificateType": "IDEVID",
   "caVendor": "DigiCert",
   "caPlatform": "DC1",
   "platformVersion": "v1",
   "additionalAttributes": {
     "vendorSpecificProfileAttributes": {
       "dC1": {
         "divisionId": "test",
         "deviceProfileId": "test",
         "enrollmentProfileId": "test"
      }
     }
   }
 },
 "productionUserIds": [
   "169c4f29-4df6-4e57-aae9-11c13b058bfc"
 ],
 "revocationUserIds": [
   "169c4f29-4df6-4e57-aae9-11c13b058bfc"
 ]
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# GET /profiles/{profileId}

  • Retrieves profile details by ID (PKI Admin) Parameters
Name Located in Description Required Schema
profileId path Profile ID Yes string

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. Profile was not found

# PUT /profiles/{profileId}

  • Updates MPKI/DC1 certificate profile (PKI Admin) Parameters
Name Located in Description Required Schema
profileId path Profile ID Yes string
  • Responses
Code Description Schema
204 Profile updated
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# Certificate Proxies

# GET /proxies

  • Retrieves list of factory proxy details (Production Admin)
  • Parameters-No parameters needed.

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. Profile was not found

# POST /proxies

MPKI

  • Creates factory proxy (Production Admin)
  • Parameters-No parameters needed.

Request body example

{
  "name": "abc",
  "proxyId": "15ac7394-837f-4b0b-95ee-dfacdb376eb9",
  "profiles": [
    {
      "profileId": "ae3b81d9-2c96-4320-aa7e-0683667946df",
      "profiletype": "Certificate_LDevId"
    }
  ],
  "applicationId": "abc",
  "secrets": {
    "internalModuleSecret": "",
    "externalModuleSecret": "",
    "imageregistry": {
      "serveraddress": "https://abbability.azurecr.io",
      "username": "a6030028-a557-420f-bb01-d280f5cbaa17",
      "password": "***"
    }
  },
  "configuration": {
    "pollingFrequency": 500
  }
}

Responses

Code Description Schema
201 Created
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

DC1

  • Creates factory proxy (Production Admin)
  • Parameters-No parameters needed.

Request body example

{
  "name": "abc",
  "proxyId": "15ac7394-837f-4b0b-95ee-dfacdb376eb9",
  "profiles": [
    {
      "profileId": "ae3b81d9-2c96-4320-aa7e-0683667946df",
      "profiletype": "Certificate_IDevId"
    }
  ],
  "applicationId": "abc",
  "secrets": {
    "internalModuleSecret": "",
    "externalModuleSecret": "",
    "imageregistry": {
      "serveraddress": "https://abbability.azurecr.io",
      "username": "a6030028-a557-420f-bb01-d280f5cbaa17",
      "password": "***"
    }
  },
  "configuration": {
    "pollingFrequency": 500
  }
}

Responses

Code Description Schema
201 Created
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# GET /proxies/{proxyId}

  • Retrieves factory proxy details (Factory Proxy, Production Admin)

Responses

Code Description Schema
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource

# DELETE /proxies/{proxyId}

  • Deletes factory proxy (Production Admin) Parameters
Name Located in Description Required Schema
ProxyId path Proxy ID Yes string

Responses

Code Description Schema
204 Profile updated
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. Profile was not found

# Enrollments

# POST /enrollments

  • This request is a command to generate new enrollment codes.
  • This will only be applicable for MPKI and not for DC1.
  • Request generation of enrollment codes (Factory Proxy)

Parameters

Name Located in Description Required Schema
moduleId header operationId generates enrollment codes for moduleId. These codes are then defined for factoryProxy Yes string

Request body example

{
  "operationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "proxyId": "a11a3192-58c1-4ff1-903b-03ade3af51ca",
  "count": 100
}

The count parameter should be between 1-2000. ProxyId should be an ID of a proxy entity registered in the Certificate Manager Service. OperationId should be a unique UUIDv4 for each request. Later on, you will use that operationId to retrieve the enrollment codes.

TIP

This request does not return the enrollment codes. It only commands the Certificate Manager Service to generate these and returns 202 (Accepted) HTTP status. To get the actual codes, you need to use the [GET] enrollments request.

Responses

Code Description Schema
202 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Proxy Not Found
409 Operation is already registered
500 API key expired or invalid

# GET /enrollments

  • It retrieves a list of operationIds that have been used to generate the enrollment codes (Factory Proxy).
  • This will only be applicable for MPKI and not for DC1.

Parameters

Name Located in Description Required Schema
moduleId header Module for which codes are generated Yes string

Responses

Code Description Schema
200 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
500 API key expired or invalid

# POST /enrollments/{operationId}/regenerate

  • Request generation of not redeemed codes (Factory Proxy)

Parameters

Name Located in Description Required Schema
moduleId header Module for which codes are generated Yes string

Responses

Code Description Schema
202 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Proxy Not Found
422 Status of operation is unprocessible
500 API key expired or invalid

# GET /enrollments/{operationId}

This call retrieves the status and enrollment codes (together with deviceIds) for a specific operationId. You have to use that endpoint in order to retrieve enrollment codes that you requested to be created via the [POST] api-enrollments request (Factory Proxy).

Parameters

Name Located in Description Required Schema
operationId path Id of the operation of enrollment codes generation Yes UUID
moduleId header Module for which codes are generated Yes string

Responses

Code Description Schema
200 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found
500 API key expired or invalid

# GET /enrollments/{operationId}/status

This call retrieves the status and enrollment codes (together with deviceIds) for a specific operationId. You have to use that endpoint in order to retrieve enrollment codes that you requested to be created via the [POST] api-enrollments request (Factory Proxy).

Parameters

Name Located in Description Required Schema
operationId path Id of the operation of enrollment codes generation Yes UUID
moduleId header Module for which codes are generated Yes string

Responses

Code Description Schema
200 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found
500 API key expired or invalid

# Certificates

MPKI

# POST /certificates

  • Signs certificate request (Factory Proxy)
  • Parameters-No parameters needed.

Request body example

{
  "proxyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "string",
  "csr": "string",
  "certificateType": "LDevID"
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Profile not found
409 Conflict
500 API key expired or invalid

IDEVID

  • Signs certificate request (Factory Proxy)
  • Parameters-No parameters needed.

Request body example

{
  "proxyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "string",
  "csr": "string",
  "certificateType": "IDevID",
  "attributes": {
    "san": {
      "custom_attributes": {
        "uniformResourceIdentifier": "string"
      }
    }
  }
}

Responses

Code Description Schema
200 Success
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Profile not found
409 Conflict
500 API key expired or invalid

# GET /certificates/{deviceId}

  • Retrieves certificate details (Factory Proxy, Production Admin, Revocation Admin)

Parameters

Name Located in Description Required Schema
deviceId path Device ID Yes UUID

Responses

Code Description Schema
200 Accepted
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found
500 API key expired or invalid

# PUT /certificates/{deviceId}/revoke

  • Revokes certificate, Applies only for MPKI (Revocation Admin)

Parameters

Name Located in Description Required Schema
deviceId path Device ID Yes UUID

Request body example

{
  "revokeReason": "key_compromise"
}

Responses

Code Description Schema
204 OK
401 Not Authorized. Either the access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found
500 API key expired or invalid
Last updated: 3/2/2023, 10:50:57 AM

← Certificate Format →

Feedback