Skip to content
NextPKI Developers

Quickstart

You need an API token. Create one in the Console under Settings → API tokens, choose the certs:read scope, and copy it - the value is shown once and stored only as a hash.

1. Check the token works

Section titled “1. Check the token works”
Terminal window
curl -sS https://api.nextpki.com/v1/auth/validate \
  -H "Authorization: Bearer $NEXTPKI_TOKEN"

A 200 confirms the token, its tenant and its scopes. Anything else means the token is wrong, revoked or out of scope - see errors.

Use https://api.nextpki.de if your tenant is pinned to the German region. Calling the wrong region will not leak data; it will simply not find your tenant.

2. List your certificates

Section titled “2. List your certificates”
Terminal window
curl -sS "https://api.nextpki.com/v1/certificates?limit=20" \
  -H "Authorization: Bearer $NEXTPKI_TOKEN"

3. Find what expires soon

Section titled “3. Find what expires soon”

There is no server-side expiry filter in v1, so sort client-side. This lists everything expiring within 30 days:

Terminal window
curl -sS "https://api.nextpki.com/v1/certificates?limit=500" \
  -H "Authorization: Bearer $NEXTPKI_TOKEN" \
| jq --arg cutoff "$(date -u -v+30d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
      || date -u -d '+30 days' +%Y-%m-%dT%H:%M:%SZ)" '
  [ .items[] | select(.not_after <= $cutoff) ]
  | sort_by(.not_after)
  | .[] | {common_name, not_after, issuer_dn}
'

4. Request a renewal

Section titled “4. Request a renewal”

Renewal needs the certs:renew scope and a CSR. Generate the key on the host that will serve the certificate - NextPKI never wants your private key:

Terminal window
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -nodes -keyout server.key -out server.csr \
  -subj "/CN=www.example.com"

You also need the connector_id of the CA connector to order through. Connectors are configured in the Console under Settings → Connectors.

Terminal window
curl -sS -X POST "https://api.nextpki.com/v1/certificates/$CERT_ID/renew" \
  -H "Authorization: Bearer $NEXTPKI_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
        --arg csr "$(cat server.csr)" \
        --arg connector "$NEXTPKI_CONNECTOR_ID" \
        '{connector_id: $connector, csr: $csr}')"

This creates a renewal in pending_approval. It does not return a certificate - an approver has to approve it first, then a worker orders it from the CA. Poll GET /v1/requests/{id} until the state reaches issued.

Next

Section titled “Next”