Certificate API — Integration Guide

This guide is for teams that want to request SSL certificates programmatically through Stanford's certificate provisioning API, rather than through the web UI.

1. Prerequisites

Before you can call the API, you need two things set up:

a. Set up a Keycloak API client

If your team doesn't already have one, request it:

b. Set up a KEYCLOAK_ID custom field on each NetDB node you need certs for

2. Get a Bearer token

_shell

TOKEN=$(curl -s -X POST \
  "https://keycloak.svc.stanford.edu/auth/realms/stanford-oauth-dev/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>" \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

Tokens are short-lived—request a fresh one for each session/script run rather than caching it long-term.

3. Build the request payload

At minimum, the payload needs:

_shell

jq -Rs '{csr: .}' your-cert.csr > payload.json

Then add the required fields:

_Python

import json

with open("payload.json") as f:
    payload = json.load(f)

payload["contact_email"] = "you@stanford.edu"
payload["server_type"] = "Apache"   # or Tomcat, Microsoft IIS, Java Web Server, RedHat Linux, Other
payload["duration"] = 199           # days

with open("payload.json", "w") as f:
    json.dump(payload, f)

A note on SANs: You only need to add a sans field if your CSR includes Subject Alternative Names beyond the primary Common Name (i.e., a multi-domain UCC certificate). For a standard single-domain certificate, leave sans out entirely—the API infers the domain from the CSR's CN. If you do include sans, it must exactly match what's actually encoded in the CSR itself, or the request will be rejected with a mismatch error telling you which hostnames are missing or extra.

4. Submit the request 

_shell

curl -s -X POST "https://certprovision-prod.iam.stanford.edu/api/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  | python3 -m json.tool

All API requests go directly to production. There is currently no separate UAT/test environment available for external teams to validate their integration against. We recommend testing your script against a low-stakes or throwaway hostname first, since your very first successful call will result in a real, issued certificate.

A successful submission returns something like:

_JSON

{
    "id": 38204,
    "cn": "your-host.stanford.edu",
    "cert_type": "normal",
    "order_number": null,
    "duration": 199,
    "server_type": "Apache/ModSSL",
    "async": true,
    "backend": "acme"
}

Certificate issuance happens asynchronously in the background—you'll be notified by email at the contact email address you provided once it's ready.

5. Retrieving your certificate

Besides the fulfillment email, every issued certificate is available for automated retrieval at:

https://certprovision-prod.iam.stanford.edu/cert/<your-hostname>

Available formats:

This is the same URL linked from the fulfillment email — you can poll it directly (e.g., on a cron schedule) rather than relying on parsing the email, which is useful if you want to automate detecting when a certificate has been renewed.

We do not currently offer a full ACME protocol endpoint with External Account Binding (EAB) for fully automated, certbot-driven renewal. This is in development for a future release.

6. Common error messages

Questions

Reach out via the UIT Authentication and Collaboration group or submit a Help ticket.