Certificates

You can use REST API v2 calls to obtain information about certificates within a specified certificate template as well as make changes to those certificates.
New for 5.8

The following table lists the properties that can be used in the body of a certificate-related request and/or are provided in the response body. (In the "Optional" column, if a default value is applicable, it is listed in angle brackets (< >). )

Resource: Certificate

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
guid String No orderBy, like

Optional on create only, but not on any subsequent uses.

 The unique identifier for this certificate.
commonName String No orderBy, like No The common name for this certificate
status String<Enum> Yes orderBy, in, eq No

ISSUED, ISSUED_AND_CONFIRMED_USE, REVOKED, or EXPIRED.

A PUT can be used to revoke the certificate.

Unrevoking the certificate changes the status to ISSUED or ISSUED_AND_CONFIRMED_USE, whichever is applicable. One caveat is that, if the certificate has expired, a PUT request for a status change will result in an "EXPIRED" status.
revokedReason String Yes orderBy, like Yes/No If changing the status to REVOKED, a reason is required.
revokedDate DateTime No orderBy Yes (ISO 8601) The date that this certificate was revoked. Will be provided if the certificate is revoked.
notValidBefore DateTime<String> No orderBy Yes (ISO 8601) The date and time after which this certificate will work.
notValidAfter DateTime<String> No orderBy No (ISO 8601) The date and time after which this certificate expires.
serialNumber String No orderBy, like No The serial number included in the certificate.
keyLength number No orderBy, like No The length of the key.
shaFingerprint String No orderBy No The SHA fingerprint of the certificate.
organization String No orderBy, like No The organization (O) included in the certificate.
organizationUnit String No orderBy, like No The organization unit (OU) included in the certificate.
locality String No orderBy, like No The locality included in the certificate.
state String No orderBy, like No The state included in the certificate.
country String No orderBy, like No The country included in the certificate.
usage RadiusUsage <Embedded> No See the "Resource: RadiusUsage" table. No See the "Resource: RadiusUsage" table.
links[] Link array No No No Self-referencing link, and links to: certificateTemplate, enrollment

Resource: RadiusUsage

Property Name Type Editable Sort/Filter Optional in Request/Response Body? Description
issued DateTime<String> No orderBy No (ISO 8601) Date/time when the certificate was issued.
lastSessionStartTime DateTime<String> No orderBy yes (ISO 8601) The time that the current (or latest) session started.
lastSessionStopTime DateTime<String> No orderBy yes (ISO 8601) The time that the latest session ended.
lastIpaddress String No orderBy, like yes The last IP address of the client, as reported via RADIUS accounting.
lastSsid String No orderBy, like yes The SSID for the latest RADIUS authentication or accounting request from the certificate.
lastMacAddress String No orderBy, like Yes The lastMacAddress string.
lastNasId String No orderBy, like yes The NAS identifier for the latest RADIUS authentication or accounting request from the certificate.
lastNasPort number No orderBy, like yes The NAS port ID for the latest RADIUS authentication or accounting request from the certificate.
lastOcp DateTime<String> No none yes ISO8601- The last time that this certificate was validated via OCSP. This timestamp is updated a maximum of once every 10 minutes.
lastPolicyAssigned String No orderBy, like yes The last policy assigned, if the template uses policies.
lastSuccess DateTime<String> No orderBy yes (ISO 8601) The last timestamp that this certificate was successfully authenticated by RADIUS.
lastFailure DateTime<String> No orderBy yes ISO8601- The last timestamp that this certificate had an unsuccessful attempt at being authenticated by RADIUS.

Certificate URIs and Actions

The following table indicates the URIs that you can append to the root URI, along with the actions you can take, and possible return codes you can receive.

Certificate URIs and Actions

URI Action Description Return Codes
/certificateTemplates/{tempGuid}/certificates GET Returns the list of certificates that were issued using the specified certificate template.

404 - Not found

401 - Unauthorized

200 - Ok
/certificateTemplates/{tempGuid}/certificates/{guid} GET Returns detailts about the specific certificate that was issued using the specified certificate template.

404 - Not found

401 - Unauthorized

200 - Ok
PUT

Allows the change of status to "REVOKED", "ISSUED, or ISSUED_AND_CONFIRMED_USE" only.

Unrevoking would change the status to ISSUED or ISSUED_AND_CONFIRMED_USE. The certificate would assume the applicable status.

If the state change request cannot be made, a "409 - Conflict" error is returned.

409 - Conflict

404 - Not found

401 - Unauthorized

200 - Ok

Example of Using GET for Certificates Within a Specific Certificate Template

This example demonstrates how to obtain information about all certificates within a specific certificate template.

URI:

This example uses the following URI: 

 https://Jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/certificateTemplates/1/certificates

where:

  • https://Jeff245.cloudpath.net/admin/apiv2 is the root URI of the Cloudpath system being used (must include https, as shown)
  • yRCjJObWR6ER is an example of an API key generated from the Configuration > API Keys section of the Cloudpath UI
  • 1 is the GUID for the certificate template from which to obtain a list of all its certificates.

Request Headers:

The following table shows the required request headers for this URI example, with an example value of an active token that must be pasted into the Authorization header value:

Request Headers

Key Value
Content-type application/json
Authorization eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqZWZmLnJob2RpZUBjb21tc2NvcGUuY29tIiwicm9sZVBrIjoiMjEwMDAiLCJhY2NvdW50QWRtaW5QayI6IjIiLCJhcGlLZXkiOiJaV2NjTGpQZUdZMGUiLCJpYXQiOjE1NzU1NzUxNTcsImV4cCI6MTU3NTU3NTQ1N30.2q4KTyDUevkAAz7mJyp529Be1-ip3EC8P06Xarmz5ao

Request Body:

None required.

Action:

Use the GET action to send the request.

Response Body:

Once the request is sent, you will receive a "Status: 200 OK" if the GET is successful. The response body provides information about the certificates from the specified certificate template. In this example, only one certificate was issued from the specified certificate template, as shown in the response body below. 

{
    "page": {
        "page": 1,
        "pageSize": 1,
        "totalCount": 1
    },
    "contents": [
        {
            "guid": "1",
            "commonName": "jeff245.cloudpath.net",
            "status": "ISSUED_AND_CONFIRMED_USE",
            "notValidBefore": "2021-01-09T19:38:34Z",
            "notValidAfter": "2024-02-09T19:38:34Z",
            "serialNumber": "698fae00f75f419d3cfc56a19b49f66c1bc604ff",
            "keyLength": 2048,
            "shaFingerprint": "80325204AB8104CCC1740408DCADFB33AC1CE19A",
            "organization": "Sample Company, Inc.",
            "organizationUnit": "IT",
            "locality": "Westminster",
            "state": "Colorado",
            "country": "US",
            "radiusUsage": {
                "issued": "2021-02-09T19:38:34Z",
                "lastIpaddress": "",
                "lastSsid": "",
                "lastNasId": "",
                "lastNasPort": "",
                "lastOcp": "2021-02-12T20:05:14Z"
            },
            "links": [
                {
                    "rel": "parent",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/certificateTemplates/1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                },
                {
                    "rel": "self",
                    "href": "https://jeff245.cloudpath.net/admin/apiv2/yRCjJObWR6ER/certificateTemplates/1/certificates/1",
                    "hreflang": null,
                    "media": null,
                    "title": null,
                    "type": null,
                    "deprecation": null
                }
            ]
        }
    ]
}

Parent topic: Certificate Templates and Related Resources