Certificates Resource

GET /{tenantGuid}/api/v1/embeddedCertificates/{embeddedCertificateGuid}

Available Since:

12.12.0

Retrieves the embedded certificate by GUID. EmbeddedCertificate is an entity that connects a Certificate object (user certificate, non-BlackBerry Dynamics user certificate, SCEP, user credential profile, and so on) to other entities, providing information about how the certificate is used, for example, the associated user, profile, or enrollments.

Samples

Sample 1 request

 GET /SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d/embeddedCertificates
 

Get the embedded certificate that is enrolled and is part of a certificate bundle (a group of certificates that can be renewed or deleted as a single element).

Sample 1 response body

 
 {
     "links": [
         {
             "rel": "user",
             "href": "https://server01:18084/SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d"
         },
         {
             "rel": "certificateEnrollments",
             "href": "https://server01:18084/SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d/embeddedCertificate/cdf5f9eb-7964-4b27-9fb8-ba038c199e5c/certificateEnrollments"
         },
         {
             "rel": "profile",
             "href": "https://server01:18084/SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d/profiles/1aba01cb-c758-4590-9fb1-527cc94fb7ba"
         },
         {
             "rel": "certificate",
             "href": "https://server01:18084/SRP00000/api/v1/pki/certificates/cdf5f9eb-7964-4b27-9fb8-ba038c199e5c"
         },
         {
             "rel": "bundle",
             "href": "https://server01:18084/SRP00000/api/v1/pki/bundles/7ebddbc5-9673-4f3b-83ff-55a5f1c70f6e"
         }
     ],
     "guid": "cdf5f9eb-7964-4b27-9fb8-ba038c199e5c",
     "name": "entrustUCP-testUser-cdf5f9eb-7964-4b27-9fb8-ba038c199e5c",
     "created": "2017-01-14T16:40:03.54Z"
 }
 

Sample 2 request

 GET /SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d/embeddedCertificates
 

Get embedded certificate that is not enrolled.

Sample 2 response body.

 
 {
     "links": [
         {
             "rel": "user",
             "href": "https://server01:18084/SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d"
         },
         {
             "rel": "profile",
             "href": "https://server01:18084/SRP00000/api/v1/users/dd93cfa3-6016-4685-8bb7-6bd8e18fc82d/profiles/3522b810-b17c-491c-bc3f-c88e48af0770"
         },
         {
             "rel": "certificate",
             "href": "https://server01:18084/SRP00000/api/v1/pki/certificates/2ab7d0e2-3f24-48c6-961a-949794f4b554"
         }
     ],
     "guid": "2ab7d0e2-3f24-48c6-961a-949794f4b554",
     "name": "TKCA_02_VF1_S_MIME_Encr.pfx",
     "created": "2017-01-01T11:04:30.45Z"
 }
 

Sample 3 request

 GET /SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/embeddedCertificates
 

Get embedded non-dynamics user certificate that is enrolled.

Sample 3 response body.

 
  "links": [
      {
            "rel": "user",
            "href": "https://server01:18084/SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b"
      },
      {
            "rel": "certificateEnrollments",
            "href": "https://server01:18084/SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/embeddedCertificates/4d355432-adfb-4a6a-9a6e-85579b0bda7b/certificateEnrollments"
      },
      {
            "rel": "profile",
            "href": "https://server01:18084/SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/profiles/b8f4940c-753e-4e60-b136-df3bcded36ab"
      },
      {
             "rel": "certificate",
             "href": "https://server01:18084/SRP00000/api/v1/pki/certificates/4d355432-adfb-4a6a-9a6e-85579b0bda7b"
      }
   ],
   "guid": "4d355432-adfb-4a6a-9a6e-85579b0bda7b",
   "name": "One_Key_Pair.pfx.pfx",
   "created": "2020-03-11T14:26:34.503Z"

 }

 

GET /{tenantGuid}/api/v1/embeddedCertificates/{embeddedCertificateGuid}/certificateEnrollments

Available Since:

12.13.0

Get a list of certificate enrollments for a specified embedded certificate. CertificateEnrollment is an entity that shows all places certificate was sent to with statuses of it's enrollment. Note: statuses for non-BlackBerry Dynamics certificates are not returned.

Samples

Sample 1 request

 GET /SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/embeddedCertificates/9b2e2079-568f-42e6-8864-7fc9afbe08ed/certificateEnrollments
 

Get a list of successful certificate enrollments.

Sample 1 response body

 
 {
     "certificateEnrollments": [
         {
             "link": {
                 "rel": "userDeviceApplication",
                 "href": "https://localhost:18084/L27221451/api/v1/users/886cb896-c8f4-4cbf-8211-ef166f73ca92/userDevices/6c81070b-97a8-4e06-bd19-c13d8497e211/applications/9b2e2079-568f-42e6-8864-7fc9afbe08ed"
             },
             "status": "VERIFIED"
         }
     ]
 }
 
 

Sample 2 request

 GET /SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/embeddedCertificates/9b2e2079-568f-42e6-8864-7fc9afbe08ed/certificateEnrollments
 

Get the certificate enrollments when the certificate enrolling was not started yet. For example, the user certificate profile is assigned to the user but this user does not have an activated device, so the system maintains the certificate and embedded certificate, but enrollments do not exist.

Sample 2 response body.

 
 {
     "certificateEnrollments": []
 }
 
 

Sample 3 request

 GET /SRP00000/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/embeddedCertificates/4d355432-adfb-4a6a-9a6e-85579b0bda7b/certificateEnrollments
 

Get the certificate enrollments for a non-BlackBerry Dynamics certificate

Sample 3 response body.

 
 {
     "certificateEnrollments": [
         {
             "link": {
                 "rel": "userDevice",
                 "href": "https://localhost:18084/L49445226/api/v1/users/2c227cd6-53af-4a3f-9be4-2f613363c78b/userDevices/d783c30f-6a9f-45d0-88aa-9e992c8c428c"
             }
         }
     ]
 }
 
 

DELETE /{tenantGuid}/api/v1/pki/bundles/{certificateBundleGuid}

Available Since:

12.12.0

Delete certificate bundle including all it's certificates by given certificate bundle GUID. Deletion implies removing all bundle certificates from a server and from managed clients (device or BlackBerry Dynamics app) if related certificates are already enrolled to a client. For bundle with enrolled certificates operation is executed asynchronously because requires messaging with managed device or app.

Not all certificate bundles are supporting operation by their nature. To determine if operation is supported for a particular certificate bundle API client should analyze DELETE method availability using OPTIONS method.

GET /{tenantGuid}/api/v1/pki/bundles/{certificateBundleGuid}

Available Since:

12.12.0

Get certificate bundle by given GUID. Certificate bundle groups several certificates that can be enrolled deleted or renewed only together.

Reference to a certificate bundle resource can be obtained from related embedded certificate by querying list of embedded certificates for a user. Each embedded certificate has an array of links where the link with rel:'bundle' has href to a certificate bundle (with particular certificate bundle GUID). Embedded certificate has reference to a certificate bundle only if related certificate is a member of a certificate bundle.

Sample request

Get a certificate bundle that contains two certificates.

Sample response body.

 
 {
     "links": [
         {
             "rel": "certificate",
             "href": "https://server01:18084/SRP00000/api/v1/pki/certificates/2ab7d0e2-3f24-48c6-961a-949794f4b554"
         },
         {
             "rel": "certificate",
             "href": "https://server01:18084/SRP00000/api/v1/pki/certificates/1aba01cb-c758-4590-9fb1-527cc94fb7ba"
         }
     ],
     "guid": "dd93cfa3-6016-4685-8bb7-6bd8e18fc82d"
 }
 

OPTIONS /{tenantGuid}/api/v1/pki/bundles/{certificateBundleGuid}

Available Since:

12.12.0

Get available methods for a particular certificate bundle by given certificate bundle GUID. Different certificate types support different ranges of operations. API client should request this method and analyze returned Allow HTTP header in order to determine which operations from the following are supported:

• GET and HEAD methods are always supported for certificate bundle
• DELETE: certificate bundle can be deleted
• PATCH: certificate bundle can be renewed

PATCH /{tenantGuid}/api/v1/pki/bundles/{certificateBundleGuid}

Available Since:

12.12.0

Renew certificate bundle including all it's certificates by given certificate bundle GUID. Renewing implies instructing managed device or app to start renew process for all certificates that belong to this certificate bundle so that devices will obtain next certificates from PKI infrastructure. Operation is executed asynchronously because requires messaging with managed device or app.

Not all certificate bundles are supporting operation by their nature. To determine if operation is supported for a particular certificate bundle API client should analyze PATCH method availability using OPTIONS method.

DELETE /{tenantGuid}/api/v1/pki/certificates/{certificateGuid}

Available Since:

12.12.0

Delete certificate by given certificate GUID. Deletion implies removing certificate from a server and from managed client (device or BlackBerry Dynamics app) if this certificate is already enrolled to a client. For enrolled certificates operation is executed asynchronously because requires messaging with managed device or app.

Not all certificates are supporting operation by their nature. To determine if operation is supported for a particular certificate API client should analyze DELETE method availability using OPTIONS method.

Certificates that are members of a certificate bundle can't be deleted individually. Only whole bundle can be deleted using delete certificate bundle method.

GET /{tenantGuid}/api/v1/pki/certificates/{certificateGuid}

Available Since:

12.12.0

Get a public key certificate by the certificate GUID. The certificate is returned in a DER-encoded X.509 format. The file name for the certificate is returned in a Content-Disposition response header. The API client can retrieve the certificate to extract details like the expiration date, subject, issuer, and so on.

As of API version 12.12.0, this method supports only user certificates for managed devices or BlackBerry Dynamics apps. The supported profiles are limited to:

• User credential profiles with any connector type
• SCEP profile (only certificates installed for BlackBerry Dynamics apps)
• User certificate profiles configured for BlackBerry Dynamics apps
• Non-BlackBerry Dynamics user certificate profiles

Known limitation: In some cases, UEM can't provide the public key certificate body for managed certificates because it does not have access to the credentials that are required for the PKCS #12 container. UEM will respond with a 405 HTTP error. To determine if the certificate body can be retrieved, the API client should use the OPTIONS method to determine if the GET method is available. Known cases include:

• Any non-BlackBerry Dynamics certificate that was issued before the release of API version 12.12.0, using a user credential profile with a certification authority connection to an external PKI like Entrust or OpenTrust.
• A certificate enrolled on a managed device with a user credential profile with Entrust Smart Credentials, but only if the certificate is not delivered to any BlackBerry Dynamics app on the device.
• A user certificate for BlackBerry Dynamics apps that is uploaded but not yet enrolled for any app.

You can get the certificate reference from a related embedded certificate by querying the list of embedded certificates for a user. Each embedded certificate has an array of links, where the link with rel:'certificate' has an href to the certificate (with the GUID).

The forming rule for the fileName returned in the Content-Disposition header:

• If a certificate was uploaded by a user as a file, and belongs to a certificate bundle, the filename=[name of uploaded file WITHOUT its extension]-[certificateGUID].cer
• If a certificate was uploaded by a user as a file, and does not belong to a certificate bundle, the filename=[name of uploaded file WITHOUT its extension].cer
• If a certificate wasn't uploaded as a file (i.e. the certificate is not uploaded by the user), the filename=[policyname]-[username]-[certificateGUID].cer

OPTIONS /{tenantGuid}/api/v1/pki/certificates/{certificateGuid}

Available Since:

12.12.0

Get available methods for a particular certificate by given certificate GUID. Different certificate types support different ranges of operations. API client should request this method and analyze returned Allow HTTP header in order to determine which operations from the following are supported:

• GET and HEAD: public key certificate body can be retrieved
• DELETE: certificate can be deleted
• PATCH: certificate can be renewed

PATCH /{tenantGuid}/api/v1/pki/certificates/{certificateGuid}

Available Since:

12.12.0

Renew certificate by given certificate GUID. Renewing implies instructing managed device or app to start renew process for this certificate so that device will obtain next certificate from PKI infrastructure. Operation is executed asynchronously because requires messaging with managed device or app.

Not all certificates are supporting operation by their nature. To determine if operation is supported for a particular certificate API client should analyze PATCH method availability using OPTIONS method.

Certificates that are members of a certificate bundle can't be renewed individually. Only whole bundle can be renewed using renew certificate bundle method.