Download OpenAPI specification:Download
Enroll and manage endpoint devices — the headless Cortega Endpoint Guard service and the AI Booster 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.
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 Booster — 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.
A trusted enrollment authority. Cortega resolves a device's tenant from the CA that signed its client certificate.
curl -H "Authorization: Bearer $CORTEGA_API_KEY" \ "https://$CORTEGA_HOST/api/v1/edge/enrollment/cas"
[- {
- "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"
}
]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.
| name required | string |
| generate_cortega_ca | boolean Have Cortega generate the CA and keep the key. Mutually exclusive with |
| ca_cert_pem | string Your CA certificate, PEM. Cortega never receives the private key. |
object Optional constraints on the certificates this CA may mint. |
{- "name": "string",
- "generate_cortega_ca": true,
- "ca_cert_pem": "string",
- "subject_policy": { }
}{- "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"
}A disabled CA stops validating new devices and cannot mint certificates. Requires edge:write.
| id required | string <uuid> The enrollment CA's id. |
| trust_enabled required | boolean |
{- "trust_enabled": true
}{- "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"
}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.
| id required | string <uuid> The enrollment CA's id. |
| 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). |
| tenant_id | string Optional tenant UUID; must match the CA tenant and the API key's tenant. |
| valid_days | integer <= 1095 Default: 365 |
{- "device_id": "string",
- "name": "string",
- "tenant_id": "string",
- "valid_days": 365
}{- "device_id": "string",
- "cert_pem": "string",
- "key_pem": "string",
- "ca_bundle_pem": "string",
- "identity_pem": "string",
- "expires_at": "2019-08-24T14:15:22Z",
- "fingerprint_sha256": "string"
}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.
| email required | string <email> |
| cortega_base_url | string The base URL the device should reach Cortega at (e.g. https://cortega.company.internal). Must be this installs console address (CORTEGA_APP_ORIGIN) or the target tenants own sign-in address ( |
{- "cortega_base_url": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "cortega_base_url": "string",
- "invite_url": "string",
- "code": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Invalidates the old link and returns a new one. Requires edge:write.
| id required | string |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
- "cortega_base_url": "string",
- "invite_url": "string",
- "code": "string",
- "created_at": "2019-08-24T14:15:22Z"
}curl -H "Authorization: Bearer $CORTEGA_API_KEY" \ "https://$CORTEGA_HOST/api/v1/edge/agents"
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "device_id": "string",
- "hostname": "string",
- "serial_number": "string",
- "platform": "string",
- "agent_version": "string",
- "active_clients": [
- "string"
], - "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"
}
]Requires edge:read.
| id required | string <uuid> The person-device seat record id (the |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "device_id": "string",
- "hostname": "string",
- "serial_number": "string",
- "platform": "string",
- "agent_version": "string",
- "active_clients": [
- "string"
], - "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"
}Removes the device record. A device enrolled by client certificate can re-enroll unless you also disable or narrow its CA. Requires edge:write.
| id required | string <uuid> The person-device seat record id (the |
Calls the AI Booster agent makes with the enrolled device's own token, not an API key. Listed for completeness; an integration does not call them.
Called by the AI Booster agent for each Bash, Write or Edit call Claude Code proposes. It needs the device token, so an edge:write API key cannot call it. Order: device or session suspended (deny, halt); policy rules, where an active exception for the matched rule turns that action into allow; repeated-denial escalation (deny, halt). With the setting off for the tenant the answer is allow with no decision_id. With request_exception true no check runs: the device asks for an exception to a denial it received.
| tool | string Claude Code tool name: Bash, Write or Edit are checked. |
object
| |
| cwd | string |
| home | string <= 256 characters The user's home folder on the device, so absolute paths under it match |
| session_id | string |
| client | string |
| client_version | string |
object Only AWS_PROFILE, AWS_REGION, AWS_DEFAULT_REGION, AWS_ACCESS_KEY_ID and AWS_ROLE_ARN are read. | |
object Every profile in the developer's ~/.aws/config, keyed by profile name. | |
| request_exception | boolean |
| decision_id | string <uuid> |
| note | string <= 2000 characters |
| file_exception_request | boolean Optional. When true and this call is denied, the server files an exception request itself and returns |
Array of objects (ToolCheckScriptFinding) <= 20 items Optional. What the agent found inside scripts the command runs, scanned on the device. Only findings are sent, never file content. Each match is checked as an |
{- "tool": "string",
- "input": { },
- "cwd": "string",
- "home": "string",
- "session_id": "string",
- "client": "claude_code",
- "client_version": "string",
- "env": {
- "property1": "string",
- "property2": "string"
}, - "profiles": {
- "property1": {
- "role_arn": "string",
- "sso_account_id": "string",
- "source_profile": "string"
}, - "property2": {
- "role_arn": "string",
- "sso_account_id": "string",
- "source_profile": "string"
}
}, - "request_exception": true,
- "decision_id": "35405636-5581-4a10-b063-a74afe2ca763",
- "note": "string",
- "file_exception_request": true,
- "script_findings": [
- {
- "path": "string",
- "sha256": "string",
- "scanner_version": 1,
- "truncated": true,
- "unreadable": true,
- "matches": [
- {
- "service": "ec2",
- "action": "terminate-instances",
- "line": 0
}
]
}
]
}{- "console_url": "string",
- "exception_request_id": "034e329d-5271-4d31-8822-f4bc1715dd81",
- "decision": "allow",
- "halt": true,
- "reason": "string",
- "decision_id": "35405636-5581-4a10-b063-a74afe2ca763",
- "rule": "string"
}Sent after the server is back, one record per command. A record holds no command text. It is stored as a decision row marked offline with rule offline_unreachable.
| tool required | string <= 64 characters |
| session_id | string <= 200 characters |
| tool_use_id | string <= 200 characters A record sent twice with the same value is stored once. |
| applied required | string Enum: "allow" "ask" "deny" |
| on_unreachable required | string Enum: "allow" "ask" "deny" |
| reason required | string Value: "unreachable" |
| home | string <= 256 characters Accepted for symmetry with the check request. Not used. |
| at_ms required | integer <int64> When it happened on the device, Unix milliseconds. A time in the future or older than 30 days is stored as now. |
Array of objects (ToolCheckScriptFinding) <= 20 items Optional summary of script findings for the call, stored on the decision row. Same shape as in the tool-check request. |
{- "tool": "string",
- "session_id": "string",
- "tool_use_id": "string",
- "applied": "allow",
- "on_unreachable": "allow",
- "reason": "unreachable",
- "home": "string",
- "at_ms": 0,
- "script_findings": [
- {
- "path": "string",
- "sha256": "string",
- "scanner_version": 1,
- "truncated": true,
- "unreadable": true,
- "matches": [
- {
- "service": "ec2",
- "action": "terminate-instances",
- "line": 0
}
]
}
]
}