Skip to main content
API docs by Redocly

Cortega Edge API (1.0.0)

Download OpenAPI specification:Download

Enroll and manage endpoint devices — the headless Cortega Endpoint Guard service and the AI Verifier desktop app — from your own provisioning, MDM, or asset-management system instead of the console, one device at a time.

A tenant admin issues an API key under System → API Access; the key is a bearer token prefixed crt_ and is shown once at creation. (Distinct from the gateway's ck_ virtual key.)

Authorization: Bearer crt_...

Every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset; a 429 includes Retry-After (seconds).

The key's tenant is resolved from the key itself — never from a request parameter — so a key can only ever act on its own tenant's devices and CAs.

Scope Grants
edge:read list enrollment CAs and enrolled devices
edge:write everything in edge:read, plus create/disable CAs, mint client certificates, create invitations, and deprovision devices

These same endpoints also accept a console session, so the two callers stay in sync. The edge feature must be included in the install license.

Two ways to roll out at scale

Headless Endpoint Guard — client certificates. Create one enrollment CA (POST /edge/enrollment/cas), then call POST /edge/enrollment/cas/{id}/client-certs once per device from your provisioning system. Drop the returned identity_pem on the machine along with the Cortega address; on startup the service presents the certificate and registers itself — no console step per device.

AI Verifier — invitations. The desktop app is tied to a person, so it cannot be enrolled by an admin credential alone. Call POST /edge/sso/invitations once per user to mint an invitation link, distribute the links, and each user finishes with SSO in their browser. (Domain-matched SSO — configured per tenant — needs no API call at all.)

Use GET /edge/agents to reconcile what is enrolled and DELETE /edge/agents/{id} to deprovision.

Enrollment CAs

A trusted enrollment authority. Cortega resolves a device's tenant from the CA that signed its client certificate.

List the tenant's enrollment CAs

Requires edge:read.

Authorizations:
cortegaApiKey

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/edge/enrollment/cas"

Response samples

Content type
application/json
[
  • {
    }
]

Create an enrollment CA

Either import your own CA certificate (ca_cert_pem; Cortega never sees the private key — requires the MDM device-auth feature) or have Cortega generate one (generate_cortega_ca: true — requires the Cert Manager feature). Requires edge:write.

Authorizations:
cortegaApiKey
Request Body schema: application/json
required
name
required
string
generate_cortega_ca
boolean

Have Cortega generate the CA and keep the key. Mutually exclusive with ca_cert_pem.

ca_cert_pem
string

Your CA certificate, PEM. Cortega never receives the private key.

object

Optional constraints on the certificates this CA may mint.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "generate_cortega_ca": true,
  • "ca_cert_pem": "string",
  • "subject_policy": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "mode": "generated",
  • "ca_cert_pem": "string",
  • "trust_enabled": true,
  • "has_private_key": true,
  • "subject_policy": { },
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Enable or disable a CA

A disabled CA stops validating new devices and cannot mint certificates. Requires edge:write.

Authorizations:
cortegaApiKey
path Parameters
id
required
string <uuid>

The enrollment CA's id.

Request Body schema: application/json
required
trust_enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "trust_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "mode": "generated",
  • "ca_cert_pem": "string",
  • "trust_enabled": true,
  • "has_private_key": true,
  • "subject_policy": { },
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Client certificates

Per-device identities minted from an enrollment CA.

Mint a per-device client certificate

The bulk-enrollment primitive: call once per device. The CA must be enabled and must have a private key (a generated CA, or an imported CA whose key you also uploaded). Requires edge:write.

Authorizations:
cortegaApiKey
path Parameters
id
required
string <uuid>

The enrollment CA's id.

Request Body schema: application/json
required
device_id
required
string

Your stable identifier for the machine. Embedded in the certificate.

email
required
string <email>

The user the device belongs to. Embedded in the certificate.

name
string

Optional human label (e.g. the asset name).

valid_days
integer <= 1095
Default: 365

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "device_id": "string",
  • "email": "[email protected]",
  • "cert_pem": "string",
  • "key_pem": "string",
  • "ca_bundle_pem": "string",
  • "identity_pem": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "fingerprint_sha256": "string"
}

Invitations

Single-use SSO enrollment links for the AI Verifier desktop app.

Create an AI Verifier enrollment invitation

Mints a single-use link carrying the Cortega address, the tenant, and the expected email. The user pastes it into the app's Enterprise Sign in tab and completes SSO. Requires edge:write and the edge SSO feature.

Authorizations:
cortegaApiKey
Request Body schema: application/json
required
email
required
string <email>
cortega_base_url
required
string

The base URL the device should reach Cortega at (e.g. https://cortega.company.internal).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "[email protected]",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "cortega_base_url": "string",
  • "invite_url": "string",
  • "code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Issue a fresh code for an invitation

Invalidates the old link and returns a new one. Requires edge:write.

Authorizations:
cortegaApiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "[email protected]",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "cortega_base_url": "string",
  • "invite_url": "string",
  • "code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Devices

The registry of enrolled endpoint devices.

List enrolled devices

Requires edge:read.

Authorizations:
cortegaApiKey

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/edge/agents"

Response samples

Content type
application/json
[
  • {
    }
]

Get one enrolled device

Requires edge:read.

Authorizations:
cortegaApiKey
path Parameters
id
required
string <uuid>

The device record's id (the id from GET /edge/agents, not your device_id).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "device_id": "string",
  • "user_email": "[email protected]",
  • "hostname": "string",
  • "serial_number": "string",
  • "platform": "string",
  • "agent_version": "string",
  • "active_clients": [
    ],
  • "identity_method": "unknown",
  • "enrollment_ca_id": "a76665ba-f340-4487-ba22-94c476a1de8b",
  • "enrollment_ca_name": "string",
  • "client_cert_fingerprint": "string",
  • "ca_trusted": true,
  • "tls_interception_enabled": true,
  • "system_proxy_enabled": true,
  • "last_ip": "string",
  • "registered_at": "2019-08-24T14:15:22Z",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Deprovision a device

Removes the device record. A device enrolled by client certificate can re-enroll unless you also disable or narrow its CA. Requires edge:write.

Authorizations:
cortegaApiKey
path Parameters
id
required
string <uuid>

The device record's id (the id from GET /edge/agents, not your device_id).

Responses