Certificate Manager REST API v2

The v2 REST API is located at https://certs.it.vt.edu/api/v2.

See the REST API overview for authentication setup and prerequisites.

Client Example

import jwt
import sys
import time
import requests

VALIDITY_PERIOD = 12  # hours

issuer = sys.argv[1]
key_path = sys.argv[2]

with open(key_path, 'r') as f:
    key = f.read()

now = int(time.time())
claims = {
    'iss': 'uusid={0},ou=services,dc=vt,dc=edu'.format(issuer),
    'sub': 'uusid={0},ou=services,dc=vt,dc=edu'.format(issuer),
    'iat': now,
    'exp': now + VALIDITY_PERIOD * 60 * 60,
}
token = jwt.encode(claims, key, algorithm='RS256')

base_url = 'https://certs.it.vt.edu/api/v2'
headers = {'Authorization': 'Bearer ' + token}

# Query for ACME certs expiring within the next 30 days
response = requests.get(base_url + '/certs', headers=headers,
                        params={'profile': 'INCOMMON_SERVER_ACME', 'expiring': 30})
print(response.text)

What’s new in v2

v1 supports a single search criterion at a time (by=x&keyword=y). v2 accepts any combination of filter parameters simultaneously; all provided parameters are ANDed together. At least one parameter must be supplied.

Certs Resource

GET /api/v2/certs

Parameter Type Match
cn string Exact match against common name. Prefix with % for suffix wildcard (e.g. %vt.edu).
username string Exact match against requester PID.
email string Exact match against requester email.
serial string Exact match against certificate serial number.
expiring integer Certs whose expiration falls within the next N days (future only).
expired boolean true: only certs already expired; false: only certs still within their validity window.
status string Filter by certificate status: Valid, Expired, Revoked, or Unknown (case-sensitive).
profile string Filter by profile: INCOMMON_SERVER, INCOMMON_SERVER_ACME, MIDDLEWARE_CLIENT, INCOMMON_USER.
issuer string Substring match against the certificate issuer distinguished name.

Responses

Code Meaning
200 Search completed; returns matching certificates or empty list.
400 No filter parameters were provided.

Example — certs expiring within 30 days on the ACME profile:

GET /api/v2/certs?profile=INCOMMON_SERVER_ACME&expiring=30

Example — certs with a common name ending in .vt.edu requested by a specific user:

GET /api/v2/certs?cn=%25vt.edu&username=waconley

Note: When constructing URLs manually, % must be percent-encoded as %25.

Response format

[
  {
    "encoded": "",
    "subject": "",
    "issuer": "",
    "serial": "",
    "status": "",
    "notBefore": "",
    "notAfter": "",
    "request": {
      "email": "",
      "commonName": "",
      "subjectAltNames": [],
      "profile": ""
    }
  }
]