User certificate management (/usercerts/)

URL: https://[server_name]/api/[api_version]/usercerts/

This endpoint is used to renew and revoke user certificates.

Supported fields

Field	Display name	Type	Required	Other restrictions
cert_id	Certificate ID of the certificate to renew	string	Yes, if renewing user certificate
status	User certificate status	string	Yes, if revoking or un-revoking user certificate	Either "active", "pending", "expired", or "revoked".
revocation_reason	Revocation reason	string	Yes, if revoking user certificate	Either "Unspecified", "Key Compromise", "CA Compromise", "Affiliation Changed", "Superseded", "Cessation Of Operation", or "Certificate Hold"
csr	Certificate signing request	CSR file	Yes, if renewing user certificate	Subject in the CSR must match the subject of the certificate specified by cert_id.
expiry	Number of days until new certificate expires	integer	Yes, if renewing user certificate
revoke_old	Revoke previous certificate upon successful renewal	boolean	No	Default is set to "false" if not specified.

Allowed methods

HTTP method	Resource URI	Action
GET	/api/v1/usercerts/	Get all user certificates.
GET	/api/v1/usercerts/pem/	Get all user certificates in PEM format.
GET	/api/v1/usercerts/[id]/	Get a specific user certificate with ID.
POST	/api/v1/usercerts/renew/	Renew a user certificate. Requires 'cert_id', 'csr', and 'expiry'.
PATCH	/api/v1/usercerts/[id]	Revoke a user certificate with ID. To revoke a user certificate, set the status field to "revoked" and the revocation_reason to one of the revocation reasons.
PATCH	/api/v1/usercerts/[id]	Un-revoke a user certificate with ID. If a user certificate was revoked with revocation_reason set to "Certificate Hold", it can be un-revoked by setting the status field to active.

Allowed filtering

Field	Lookup Expressions	Description
subject	exact, iexact, contains, icontains

Example

Get user certificates:

curl -k -v \

-u "[webadmin]:[hash]" \

https://[FAC_IP]/api/v1/usercerts/

Response:

{

"id": 1,

"cert_id": "user_cert",

"expiry": "2019-08-15T01:02:07+00:00",

"issuer": "issuer_cert | C=CA, ST=BC, L=Burnaby, O=Fortinet, OU=RD, CN=test, emailAddress=####@####.com",

"revocation_reason": null,

"serial": "0122A3",

"status": "Active",

"subject": "/C=CA/ST=BC/L=Burnaby/O=o/OU=RD/CN=test"

}

Get user certificates in PEM format:

curl -k -v \

-u "[webadmin]:[hash]" \

https://[FAC_IP]/api/v1/usercerts/pem/

Response:

{

"cert_id": "user_cert",

"certificate": "-----BEGIN CERTIFICATE-----\n###################################\n-----END CERTIFICATE-----\n"

}

Renew a user certificate:

curl -k -X POST \

https://[FAC_IP]/api/v1/usercerts/renew/ \

-H 'content-type: multipart/form-data' \

-u '[webadmin]:[hash]' \

-F 'cert_id=user_cert' \

-F 'csr=@/path/to/csr/*.csr' \

-F 'expiry=[Number of days until new certificate expires]' \

-F 'revoke_old=[true/false; optional]'

Response:

{

"cert_id": "new_user_cert",

"certificate": "-----BEGIN CERTIFICATE-----\n###################################\n-----END CERTIFICATE-----\n"

}

Revoke a user certificate:

curl -k -v \

-X PATCH \

-H 'Content-Type: application/json' \

-u '[webadmin]:[hash]' \

-d '{"status":"revoked", "revocation_reason":"Certificate Hold"}' \

https://[FAC_IP]/api/v1/usercerts/1/

Response:

{

"cert_id": "user_cert",

"expiry": "2019-08-15T01:02:07+00:00",

"id": 1,

"issuer": "issuer_cert | C=CA, ST=BC, L=Burnaby, O=Fortinet, OU=RD, CN=test, emailAddress=####@####.com",

"revocation_reason": "Certificate Hold",

"serial": "0122A3",

"status": "Revoked",

"subject": "/C=CA/ST=BC/L=Burnaby/O=o/OU=RD/CN=test"

}

Un-revoke a user certificate:

curl -k -v \

-X PATCH \

-H 'Content-Type: application/json' \

-u '[webadmin]:[hash]' \

-d '{"status":"active"}' \

https://[FAC_IP]/api/v1/usercerts/1/

Response:

{

"cert_id": "user_cert",

"expiry": "2019-08-15T01:02:07+00:00",

"id": 1,

"issuer": "issuer_cert | C=CA, ST=BC, L=Burnaby, O=Fortinet, OU=RD, CN=test, emailAddress=####@####.com",

"revocation_reason": null,

"serial": "0122A3",

"status": "Active",

"subject": "/C=CA/ST=BC/L=Burnaby/O=o/OU=RD/CN=test"

}