Certificates and onboarding API
The certificates API manages the tenant’s certificate authorities, issues and revokes client, server and RadSec certificates, configures server certificates for EAP, RadSec and the console, maintains the trusted CA store, and configures SCEP enrolment (with Microsoft Intune as the challenge provider). It backs the console pages Certificates › Certificate authorities, Certificates › Issued certificates, Certificates › Server certificates and Certificates › Trusted CAs.
Base path and permissions
Section titled “Base path and permissions”Tenant routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Platform routes are under /api/v1/platform. Every admin route needs a bearer token (see API overview). OCSP, CRL and SCEP are public and described in Public endpoints.
| Permission | Grants |
|---|---|
onboard:read |
Every tenant GET route. |
onboard:write |
Every tenant POST, PUT, PATCH and DELETE route. Changing the platform server certificates (platform-eap, platform-radsec, platform-https) also needs a platform administrator. |
platform:admin |
The platform root CA routes. |
Lists use the standard envelope {"items": [...], "total": N} with ?q=&limit=&offset= (limit defaults to 50, at most 1000). Times are RFC 3339 UTC. Every change is written to the audit log (object types pki_ca, certificate, onboard_settings, server_cert, scep_challenge, trust_store); private keys, PKCS#12 passwords and challenges never appear in audit details.
Route summary
Section titled “Route summary”| Method | Path | Permission |
|---|---|---|
| GET | /cas |
onboard:read |
| GET | /cas/{id} |
onboard:read |
| GET | /cas/{id}/download |
onboard:read |
| POST | /cas/{id}/rotate |
onboard:write |
| GET | /certificates |
onboard:read |
| POST | /certificates |
onboard:write |
| GET | /certificates/summary |
onboard:read |
| POST | /certificates/bulk-revoke |
onboard:write |
| GET | /certificates/{id} |
onboard:read |
| GET | /certificates/{id}/download |
onboard:read |
| POST | /certificates/{id}/revoke |
onboard:write |
| GET | /onboard-settings |
onboard:read |
| PUT | /onboard-settings |
onboard:write |
| POST | /onboard-settings/intune-test |
onboard:write |
| GET | /server-certs |
onboard:read |
| GET | /server-certs/{scope} |
onboard:read |
| GET | /server-certs/{scope}/download |
onboard:read |
| POST | /server-certs/{scope}/generate |
onboard:write |
| POST | /server-certs/{scope}/upload |
onboard:write |
| DELETE | /server-certs/{scope} |
onboard:write |
| GET | /pki-status |
onboard:read |
| GET | /trust-store |
onboard:read |
| POST | /trust-store |
onboard:write |
| GET | /trust-store/public |
onboard:read |
| PUT | /trust-store/public |
onboard:write |
| PATCH | /trust-store/{id} |
onboard:write |
| DELETE | /trust-store/{id} |
onboard:write |
| GET | /trust-store/{id}/download |
onboard:read |
| GET | /scep-challenges |
onboard:read |
| POST | /scep-challenges |
onboard:write |
| DELETE | /scep-challenges/{id} |
onboard:write |
| POST | /nads/{id}/radsec-cert |
onboard:write |
| GET | /api/v1/platform/pki/root |
platform:admin |
| POST | /api/v1/platform/pki/root |
platform:admin |
| GET | /api/v1/platform/pki/root/download |
platform:admin |
CA hierarchy
Section titled “CA hierarchy”kind |
Scope | Issues |
|---|---|---|
platform_root |
Platform (read-only for tenants) | The tenant CAs and the platform EAP, RadSec and console server certificates. Devices and network devices trust it. |
onboard |
Tenant | EAP-TLS client certificates, tenant server certificates, the tenant EAP identity and the SCEP RA. Named <tenant name> Onboard CA. |
radsec |
Tenant | RadSec client certificates for network devices and site connectors. Named <tenant name> NAD CA. |
Issued certificates carry an OCSP URL (/ocsp/{ca-id}), a CA issuers URL (/crl/{ca-id}.crt) and a CRL distribution point (/crl/{ca-id}.crl) on the PKI’s public URL. Serial numbers are 16 random bytes, shown as lower-case hex. not_before is set one hour in the past to allow for clock skew.
Rotation creates a new active CA of the same kind and marks the old one retiring. A retiring CA stays trusted and keeps answering OCSP and CRL requests; it is retired automatically once none of its certificates is still valid.
Certificate authorities
Section titled “Certificate authorities”GET /cas
Section titled “GET /cas”Permission: onboard:read
The tenant’s CAs (every status) and the active platform root. Filters: kind (platform_root, onboard, radsec), status (active, retiring, retired).
{"items": [{ "id": "87df6475-…", "tenant_id": "8e6744f2-…", "kind": "onboard", "name": "Contoso Onboard CA", "parent_id": "50a983b2-…", "status": "active", "read_only": false, "subject": "/O=Contoso/OU=Onboard/CN=Contoso Onboard CA", "common_name": "Contoso Onboard CA", "serial": "55a8fc3bb6662463d0a78e91d8938054", "ski": "DB:8A:D0:DC:…", "key_type": "rsa2048", "not_before": "2026-10-29T12:00:21Z", "not_after": "2036-10-26T13:00:21Z", "fingerprint_sha1": "93:87:96:…", "fingerprint_sha256": "B1:2F:AD:…", "ocsp_url": "http://pki.contoso.com/ocsp/87df6475-…", "crl_url": "http://pki.contoso.com/crl/87df6475-….crl", "cert_url": "http://pki.contoso.com/crl/87df6475-….crt", "crl_number": 3, "crl_next_update": "2026-11-05T12:00:00Z", "issued_count": 12, "valid_count": 10, "revoked_count": 2, "created_at": "…"}], "total": 3}The platform root has tenant_id: null, parent_id: null and read_only: true.
GET /cas/{id}
Section titled “GET /cas/{id}”Permission: onboard:read. The CA object plus cert_pem. Only the tenant’s own CAs and the platform root; anything else returns 404.
GET /cas/{id}/download
Section titled “GET /cas/{id}/download”Permission: onboard:read
?format=pem (default, application/x-pem-file), der (application/pkix-cert) or chain (PEM of the CA and its parents up to the root).
curl -s -o contoso-onboard-ca.pem "$AIRGATE/api/v1/t/$TENANT/cas/$CA_ID/download?format=chain" \ -H "Authorization: Bearer $TOKEN"POST /cas/{id}/rotate
Section titled “POST /cas/{id}/rotate”Permission: onboard:write
No body. Response 201: the new CA (with cert_pem). Returns 403 for the platform root and 409 when the CA is not active.
Issued certificates
Section titled “Issued certificates”Certificate object
Section titled “Certificate object”{"id": "8e2a166b-…", "tenant_id": "8e6744f2-…", "ca_id": "87df6475-…", "ca_name": "Contoso Onboard CA", "serial": "49683155ae20d48bf7a0fa378da5bc56", "kind": "client", "status": "valid", "subject": "/O=Contoso/OU=BYOD/CN=alice@contoso.com", "common_name": "alice@contoso.com", "issuer": "/O=Contoso/OU=Onboard/CN=Contoso Onboard CA", "sans": {"dns": [], "email": ["alice@contoso.com"], "upn": ["alice@contoso.com"], "uri": ["urn:dev:mac:02005e100001"], "ip": []}, "owner": "alice@contoso.com", "device_id": null, "device_mac": "02:00:5e:10:00:01", "device_name": "Alice Laptop", "device_os": "Windows 11", "nad_id": null, "key_type": "rsa2048", "issued_via": "admin", "not_before": "…", "not_after": "…", "revoked_at": null, "revoke_reason": "", "fingerprint_sha256": "12:02:ED:…", "created_at": "…", "pem": "-----BEGIN CERTIFICATE-----\n…"}| Field | Meaning |
|---|---|
kind |
client, server or radsec. |
status |
valid, revoked (with revoked_at and revoke_reason) or expired. |
issued_via |
admin (key generated by Airgate), csr, scep, scep-intune (SCEP validated by Intune), nad (network device RadSec certificate), edge (site connector), radsec-api, server-cert (tenant EAP identity), byod (BYOD portal) or portal (older provisioning portal). |
subject, issuer |
OpenSSL one-line form, as RADIUS shows TLS-Client-Cert-Subject. |
pem |
Only in single-certificate responses. |
GET /certificates
Section titled “GET /certificates”Permission: onboard:read
| Query parameter | Type | Meaning |
|---|---|---|
q |
string | Common name, owner, device name, device MAC or serial. |
status |
string | valid, revoked or expired (effective status: a certificate past not_after counts as expired). |
kind |
string | client, server or radsec. |
issued_via |
string | One of portal, admin, csr, scep, nad, edge, radsec-api, server-cert. |
owner |
string | Exact owner, case-insensitive. |
mac |
string | Device MAC in any notation. |
serial |
string | Serial in any hex notation. |
ca_id, device_id, nad_id |
UUID | Filters. |
expiring_days |
integer | Valid certificates that expire within N days. |
sort |
string | not_after, -not_after, owner, -owner, created_at or -created_at (default). |
curl -s "$AIRGATE/api/v1/t/$TENANT/certificates?status=valid&expiring_days=30" \ -H "Authorization: Bearer $TOKEN"POST /certificates
Section titled “POST /certificates”Permission: onboard:write
Issues a client or server certificate. Airgate either generates the key pair (returned once) or signs your CSR.
| Field | Type | Meaning |
|---|---|---|
kind |
string | client (default) or server. RadSec certificates are issued through POST /nads/{id}/radsec-cert. |
owner |
string | Owner (user). A client certificate needs owner or common_name. |
common_name |
string | Default: owner, or the CSR’s CN. At most 64 characters. A server certificate needs dns_names or a DNS-name common_name. |
device_mac, device_name, device_os |
string | Device details. device_mac adds urn:dev:mac:<hex> to the SAN. |
validity_days |
integer | Default: the setting cert_validity_days (client) or 397 (server). 1–3650; server certificates at most 825. |
key_type |
string | rsa2048, rsa3072, rsa4096, p256 or p384. Default: the setting key_type. Ignored with a CSR. |
dns_names, emails, upn, uris, ips |
Explicit subject alternative names (at most 100). Otherwise the CSR’s SANs, otherwise UPN and email from an owner that looks like user@domain. |
|
csr_pem |
string | PEM or DER PKCS#10 CSR. RSA 2048–8192, ECDSA P-256 / P-384 / P-521 or Ed25519. |
p12_password |
string | PKCS#12 password. Default: a random 26-character password. |
p12_profile |
string | legacy (3DES / SHA-1: Apple, Android, ChromeOS, older Windows) or modern (AES-256 / PBKDF2-SHA256: Windows 10 and later, Linux). |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/certificates" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"kind": "client", "owner": "alice@contoso.com", "device_mac": "02-00-5E-10-00-01", "device_name": "Alice Laptop", "validity_days": 365, "p12_profile": "modern"}'Response 201, shown only once (the private key is not stored):
{"certificate": {"…": "certificate object"}, "cert_pem": "-----BEGIN CERTIFICATE-----\n…", "chain_pem": "<issuing CA>\n<platform root>", "key_pem": "-----BEGIN PRIVATE KEY-----\n…", "pkcs12_base64": "MIIPYwIBAzCC…", "pkcs12_password": "…"}key_pem, pkcs12_base64 and pkcs12_password are omitted when a CSR was signed.
GET /certificates/summary
Section titled “GET /certificates/summary”Permission: onboard:read
{"total": 42, "by_status": {"valid": 30, "revoked": 7, "expired": 5}, "by_kind": {"client": 35, "server": 2, "radsec": 5}, "valid": 30, "revoked": 7, "expired": 5, "expired_unswept": 1, "expiring_30d": 3, "at": "…"}GET /certificates/{id}
Section titled “GET /certificates/{id}”Permission: onboard:read. The certificate object with pem.
GET /certificates/{id}/download
Section titled “GET /certificates/{id}/download”Permission: onboard:read. ?format=pem (default), der or chain (certificate, issuing CA and root).
POST /certificates/{id}/revoke
Section titled “POST /certificates/{id}/revoke”Permission: onboard:write
| Field | Type | Meaning |
|---|---|---|
reason |
string | RFC 5280 reason: unspecified (default), keyCompromise, affiliationChanged, superseded, cessationOfOperation or privilegeWithdrawn. certificateHold is refused: revocation is final. |
disconnect |
boolean | Default true. For client certificates, sends a CoA Disconnect for the certificate’s device (or, without a MAC, for the owner’s active sessions when the owner has no other valid certificate). |
Response 200: the certificate. The CRL is regenerated and OCSP answers revoked immediately. Revoking an already revoked certificate returns it unchanged. Revoking a server certificate that backs the tenant EAP identity removes that identity; the tenant falls back to the platform certificate.
POST /certificates/bulk-revoke
Section titled “POST /certificates/bulk-revoke”Permission: onboard:write
{"ids": ["…", "…"], "reason": "keyCompromise", "disconnect": true} (at most 500 IDs). Each certificate is revoked as by the single route.
{"items": [{"id": "8e2a166b-…", "status": "revoked", "serial": "49683155…"}, {"id": "0c4f…", "status": "not_found"}], "total": 2, "revoked": 1, "unchanged": 0, "not_found": 1, "failed": 0}Certificate and SCEP settings
Section titled “Certificate and SCEP settings”GET /onboard-settings · PUT /onboard-settings
Section titled “GET /onboard-settings · PUT /onboard-settings”Permission: onboard:read (GET), onboard:write (PUT)
{"cert_validity_days": 365, "key_type": "rsa2048", "scep_enabled": false, "scep_challenge": "", "scep_url": "https://airgate.contoso.com/scep/contoso", "intune_enabled": false, "intune_tenant_id": "", "intune_client_id": "", "intune_client_secret": "", "updated_at": "…"}| Field | Meaning |
|---|---|
cert_validity_days |
Default validity of client certificates, 1–3650. |
key_type |
Default key type. |
scep_enabled |
Enables the SCEP endpoint /scep/{tenant-slug}. |
scep_challenge |
Static SCEP challenge (at least 8 characters). Stored sealed, returned as "********"; sending the mask keeps it, "" clears it. |
intune_enabled |
Use Microsoft Intune as the SCEP challenge provider: a request whose challenge is not an Airgate challenge is validated with Intune, and Intune is told the result. |
intune_tenant_id |
The Entra ID tenant (directory) ID, a GUID. |
intune_client_id |
The app registration’s application (client) ID, a GUID. The app needs the application permissions Microsoft Intune API › scep_challenge_provider and Microsoft Graph › Application.Read.All. |
intune_client_secret |
Required to enable Intune. Stored sealed and returned masked. |
scep_url, updated_at |
Read-only. |
PUT merges the body over the current settings. Response 200.
POST /onboard-settings/intune-test
Section titled “POST /onboard-settings/intune-test”Permission: onboard:write
No body. Signs in with the stored Intune app registration and discovers the Intune SCEP validation service. Returns 400 when Intune is not enabled.
{"ok": true, "service_url": "https://…"}On failure: {"ok": false, "error": "could not sign in to Intune: …"}.
POST /scep-challenges
Section titled “POST /scep-challenges”Permission: onboard:write
Creates a one-time SCEP challenge for one device.
| Field | Type | Meaning |
|---|---|---|
owner |
string | Required. Becomes the certificate CN, UPN and email. |
device_name, device_mac |
string | Optional; the MAC is added to the SAN. |
ttl_minutes |
integer | 1–10080 (default 60). |
Response 201, the only time the challenge is shown. Returns 409 when SCEP is disabled.
{"challenge": "c7656dcea04a4fc0baaaa6aa14e0d916", "owner": "alice@contoso.com", "expires_at": "…", "scep_url": "https://airgate.contoso.com/scep/contoso"}GET /scep-challenges
Section titled “GET /scep-challenges”Permission: onboard:read
?status=outstanding (default: unused and unexpired), used, expired or all; q (owner, device name, MAC); limit, offset. Challenge values are never returned.
{"items": [{"id": "5b0e…", "owner": "alice@contoso.com", "device_name": "Alice MacBook", "device_mac": "02:11:22:33:44:55", "status": "outstanding", "expires_at": "…", "used_at": null, "created_at": "…"}], "total": 1}DELETE /scep-challenges/{id}
Section titled “DELETE /scep-challenges/{id}”Permission: onboard:write. Withdraws a challenge. Response 204.
Server certificates
Section titled “Server certificates”scope |
Identity | Who may change it |
|---|---|---|
platform-eap |
Shared EAP server certificate every tenant uses by default. | Platform administrators |
platform-radsec |
RadSec (TLS port 2083) server certificate. | Platform administrators |
platform-https |
The console’s HTTPS certificate (on-premises appliance). Takes effect on the next TLS handshake. | Platform administrators |
tenant-eap |
Optional per-tenant EAP server certificate. | onboard:write |
Server certificate object
Section titled “Server certificate object”{"scope": "tenant-eap", "usage": "eap", "tenant_id": "8e6744f2-…", "configured": true, "editable": true, "source": "generated", "server_names": ["contoso.radius.airgate.example"], "default_server_names": ["contoso.radius.airgate.example"], "subject": "/O=Contoso/CN=contoso.radius.airgate.example", "issuer": "/O=Contoso/OU=Onboard/CN=Contoso Onboard CA", "serial": "21d0cf09…", "key_type": "rsa2048", "not_before": "…", "not_after": "…", "fingerprint_sha256": "76:35:E0:…", "issuer_ca_id": "87df6475-…", "certificate_id": "…", "default_key_type": "rsa2048", "server_name_source": "tenant_slug", "cert_pem": "-----BEGIN CERTIFICATE-----\n…", "chain_pem": "…", "updated_at": "…"}source is generated or uploaded; editable says whether you may change the scope. The private key is never returned. Before a tenant identity exists, tenant-eap is returned with configured: false.
Server certificate routes
Section titled “Server certificate routes”| Method | Path | Permission | Behaviour |
|---|---|---|---|
| GET | /server-certs |
onboard:read |
All four scopes. |
| GET | /server-certs/{scope} |
onboard:read |
One scope; 404 for an unknown scope. |
| GET | /server-certs/{scope}/download |
onboard:read |
?format=pem, der or chain. 404 when not configured. |
| POST | /server-certs/{scope}/generate |
onboard:write (platform scopes: platform administrator) |
Issue a new certificate. |
| POST | /server-certs/{scope}/upload |
as generate | Install your own certificate and key. |
| DELETE | /server-certs/{scope} |
onboard:write |
Only tenant-eap. |
Generate takes {"server_names": ["radius.contoso.com"], "validity_days": 397, "key_type": "rsa2048"}, all optional. validity_days is 1–825 (default 397). The EAP and RadSec platform certificates always use the configured RADIUS server names; to use other names, upload a certificate. A new tenant-eap certificate is issued by the tenant’s Onboard CA and supersedes the previous one. Response 200.
Upload takes {"cert_pem": "<leaf, optionally followed by its chain>", "key_pem": "<unencrypted PKCS#8, PKCS#1 or SEC1>", "chain_pem": "<optional>"}. It returns 400 when the key does not match, the key is weaker than RSA 2048 / P-256, the leaf is a CA, expires within 24 hours, has an EKU without serverAuth, or the chain does not link up. Server names come from the leaf’s DNS SANs (or CN). Response 200.
Delete (DELETE /server-certs/tenant-eap) returns 204; the tenant goes back to the platform certificate. Platform certificates cannot be deleted.
Generated certificates are renewed automatically 30 days before expiry (or in the last third of their lifetime, if shorter). Uploaded certificates are never replaced.
GET /pki-status
Section titled “GET /pki-status”Permission: onboard:read
Status of the RADIUS certificate directory as seen by the answering node: when it was last written, the last reload signal, the tenant’s EAP certificate file, and how many of the tenant’s Onboard and NAD CAs are trusted.
{"directory": "/etc/nac/pki", "directory_enabled": true, "synced_at": "…", "sync_error": "", "reload_control": "docker", "last_reload_at": "…", "last_reload_error": "", "tenant_eap_file": "", "platform_eap_file": "/etc/nac/pki/eap-server-fullchain.pem", "platform_eap_combined": "/etc/nac/pki/eap-server-combined.pem", "trusted_client_cas": 1, "trusted_nad_cas": 1}Trusted CAs
Section titled “Trusted CAs”The trust store says which outside CAs the tenant trusts, and for what. Purposes:
| Purpose | Use |
|---|---|
eap |
Wi-Fi client certificates (EAP-TLS) issued by that CA. |
radsec |
Network devices connecting over RadSec with certificates from that CA. |
directory |
LDAPS, Active Directory and HTTP directories. |
outbound |
Webhooks, log export and other outbound connections. |
Public CAs (the well-known root bundle) can be trusted only for directory and outbound, never for eap or radsec.
Trusted CA object
Section titled “Trusted CA object”{"id": "…", "name": "Contoso Enterprise Root", "purposes": ["eap", "directory"], "enabled": true, "subject": "/DC=com/DC=contoso/CN=Contoso Enterprise Root", "issuer": "/DC=com/DC=contoso/CN=Contoso Enterprise Root", "serial_hex": "…", "fingerprint_sha256": "…", "not_before": "…", "not_after": "…", "self_signed": true, "cert_pem": "-----BEGIN CERTIFICATE-----\n…", "created_at": "…", "updated_at": "…"}GET /trust-store
Section titled “GET /trust-store”Permission: onboard:read
The imported CAs plus the public bundle setting:
{"items": [{"…": "trusted CA object"}], "total": 1, "public": {"purposes": ["directory", "outbound"], "count": 140, "allowed_purposes": ["directory", "outbound"]}}POST /trust-store
Section titled “POST /trust-store”Permission: onboard:write
| Field | Type | Meaning |
|---|---|---|
name |
string | Display name. With a bundle of several CAs, each gets its certificate’s common name. |
cert_pem |
string | One CA certificate or a PEM bundle. |
purposes |
array | At least one of eap, radsec, directory, outbound. |
Each certificate must be a CA (or a self-signed root) and not expired. Importing a CA that is already in the store updates its purposes and enables it. Response 201: {"items": [trusted CA…], "total": n}.
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/trust-store" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d "{\"name\": \"Contoso Enterprise Root\", \"purposes\": [\"eap\"], \"cert_pem\": $(jq -Rs . < contoso-root.pem)}"GET /trust-store/public · PUT /trust-store/public
Section titled “GET /trust-store/public · PUT /trust-store/public”Permission: onboard:read (GET), onboard:write (PUT)
GET lists the public root CAs (?q= filters on subject and organisation): {"items": [{"subject", "organization", "not_after", "fingerprint_sha256"}], "total": N}. PUT {"purposes": ["directory", "outbound"]} sets what the public bundle is trusted for (directory and / or outbound only). Response 200: {"purposes": [...]}.
PATCH /trust-store/{id}
Section titled “PATCH /trust-store/{id}”Permission: onboard:write. Any of {"name", "purposes", "enabled"}. Response 200: the trusted CA.
DELETE /trust-store/{id}
Section titled “DELETE /trust-store/{id}”Permission: onboard:write. Response 204.
GET /trust-store/{id}/download
Section titled “GET /trust-store/{id}/download”Permission: onboard:read. ?format=pem (default) or der.
Network device RadSec certificates
Section titled “Network device RadSec certificates”POST /nads/{id}/radsec-cert
Section titled “POST /nads/{id}/radsec-cert”Permission: onboard:write
Issues a RadSec client certificate for a network device from the tenant’s NAD CA. Body optional:
| Field | Type | Meaning |
|---|---|---|
validity_days |
integer | 1–3650 (default 730). |
key_type |
string | Default rsa2048. |
p12_password, p12_profile |
string | As for POST /certificates. |
The certificate’s CN is the device’s radsec_cert_cn, or the device ID when it has none. The device record is not changed: enable RadSec on it through the Network devices API. Response 201, shown once:
{"certificate": {"…": "certificate object", "kind": "radsec", "nad_id": "e691e4a0-…", "owner": "core-sw1"}, "cert_pem": "…", "chain_pem": "<NAD CA>\n<platform root>", "key_pem": "…", "pkcs12_base64": "…", "pkcs12_password": "…", "radsec_cert_cn": "e691e4a0-74c9-417d-aa5c-fce20c728189", "radsec_enabled": true, "server_ca_pem": "<the CA the device must trust for the RadSec server>"}Platform root CA
Section titled “Platform root CA”These routes need a platform administrator.
GET /api/v1/platform/pki/root
Section titled “GET /api/v1/platform/pki/root”The active root (active, with cert_pem), its source (generated or imported), chain (issuers above an imported intermediate), anchor (the certificate devices must trust), previous roots, and what a replacement would affect: tenants, tenant_cas, valid_certs, old_valid_certs, uploaded_server. Also default_key_type, key_types and default_validity_years for the create form.
GET /api/v1/platform/pki/root/download
Section titled “GET /api/v1/platform/pki/root/download”?what=anchor (default; what goes into an MDM trusted-certificate profile), ca (the active CA) or chain (both, PEM only); &format=pem or der.
POST /api/v1/platform/pki/root
Section titled “POST /api/v1/platform/pki/root”Replaces the platform root: create a new one, or import your own CA.
{"mode": "create", "common_name": "Contoso Root CA", "organization": "Contoso", "org_unit": "", "country": "US", "key_type": "rsa4096", "validity_years": 20, "confirm": "REPLACE"}{"mode": "import", "pkcs12": "<base64 .p12>", "password": "…", "confirm": "REPLACE"}{"mode": "import", "cert_pem": "…", "key_pem": "…", "chain_pem": "…", "confirm": "REPLACE"}confirm must be REPLACE. An imported CA needs an RSA (2048 or more) or ECDSA key matching the certificate, CA:TRUE, keyCertSign, a path length that allows a tenant CA below it, at least one more year of validity, and its issuers up to a self-signed root. Returns 400 otherwise and 409 when the CA is already in the PKI.
Every tenant’s active Onboard and NAD CA is rotated onto the new root, and generated platform and tenant server certificates are re-issued; uploaded ones are kept.
{"root": {"…": "GET view"}, "previous_root_id": "…", "tenant_cas": 2, "affected_certs": 14, "server_reissued": ["platform-https", "platform-eap", "platform-radsec", "tenant-eap (1)"], "server_kept": [], "warnings": ["the RadSec listener uses its new certificate after FreeRADIUS restarts"]}Public endpoints
Section titled “Public endpoints”These routes are on the public listener and need no API token.
POST /ocsp, POST /ocsp/{ca-id}, GET /ocsp/{base64-request}, GET /ocsp/{ca-id}/{base64-request}
An RFC 6960 / RFC 5019 responder for every CA. POST bodies must be application/ocsp-request; responses are application/ocsp-response. Answers are good (issued by the CA, valid or expired), revoked (with time and reason), unknown (never issued by that CA) or unauthorized (foreign issuer). The request nonce is echoed. Responses are signed by a delegated responder certificate per CA and are valid for one hour.
CRL and CA certificates
Section titled “CRL and CA certificates”GET /crl/{ca-id}.crl returns the DER CRL (application/pkix-crl, next update in 7 days, regenerated on every revocation). GET /crl/{ca-id}.crt or .cer returns the DER CA certificate; .pem returns PEM. Unknown CAs return 404.
GET or POST /scep/{tenant-slug}?operation=… (also /scep/{tenant-slug}/pkiclient.exe and /scep/{tenant-slug}/cgi-bin/pkiclient.exe for clients that append the NDES path). RFC 8894. Returns 404 unless SCEP is enabled; limited to 120 requests per minute per client address.
operation |
Response |
|---|---|
GetCACaps |
POSTPKIOperation SHA-256 SHA-512 AES SCEPStandard |
GetCACert |
The RA, the Onboard CA and the root (application/x-x509-ca-ra-cert). |
PKIOperation |
Enrolment (POST application/x-pki-message, or GET with message=). |
A request is authorised by, in order: a one-time challenge from POST /scep-challenges (identity from the challenge record), the static challenge (identity from the CSR: CN, SANs; owner = UPN, else email, else CN), or, when Intune is enabled, Intune’s validation. Certificates are issued with cert_validity_days and issued_via = scep (scep-intune when Intune validated the request). A failure returns pkiStatus=FAILURE.