Skip to content

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.

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.

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
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.

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.

Permission: onboard:read. The CA object plus cert_pem. Only the tenant’s own CAs and the platform root; anything else returns 404.

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).

Terminal window
curl -s -o contoso-onboard-ca.pem "$AIRGATE/api/v1/t/$TENANT/cas/$CA_ID/download?format=chain" \
-H "Authorization: Bearer $TOKEN"

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.

{"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.

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).
Terminal window
curl -s "$AIRGATE/api/v1/t/$TENANT/certificates?status=valid&expiring_days=30" \
-H "Authorization: Bearer $TOKEN"

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).
Terminal window
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.

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": "…"}

Permission: onboard:read. The certificate object with pem.

Permission: onboard:read. ?format=pem (default), der or chain (certificate, issuing CA and root).

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.

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}

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.

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: …"}.

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"}

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}

Permission: onboard:write. Withdraws a challenge. Response 204.

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
{"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.

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.

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}

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.

{"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": "…"}

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"]}}

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}.

Terminal window
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": [...]}.

Permission: onboard:write. Any of {"name", "purposes", "enabled"}. Response 200: the trusted CA.

Permission: onboard:write. Response 204.

Permission: onboard:read. ?format=pem (default) or der.

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>"}

These routes need a platform administrator.

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.

?what=anchor (default; what goes into an MDM trusted-certificate profile), ca (the active CA) or chain (both, PEM only); &format=pem or der.

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"]}

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.

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.

© 2026 Airowire Networks Pvt. Ltd. Airgate is a product of Airowire.Product · Release notes · Security