Fortinet black logo

REST API Solution Guide

User certificate management (/usercerts/)

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"

}

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"

}