Skip to main content

Cortega Edge API (1.0.0)

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.

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

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

tenant_id
string

Optional tenant UUID; must match the CA tenant and the API key's tenant.

valid_days
integer <= 1095
Default: 365

Responses

Request samples

Content type
application/json
{
  • "device_id": "string",
  • "email": "[email protected]",
  • "name": "string",
  • "tenant_id": "string",
  • "valid_days": 365
}

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 Booster desktop app.

Create an AI Booster 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
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 (.); any other value is rejected with 400. When CORTEGA_APP_ORIGIN is unset, the host the request arrived on is also accepted. Optional: empty or omitted uses the tenants sign-in address, else the console address, else the request host.

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 person-device seat record id (the id from GET /edge/agents, not the shared machine 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 person-device seat record id (the id from GET /edge/agents, not the shared machine device_id).

Responses

Tool governance (device)

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.

Check one proposed command

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.

Authorizations:
deviceToken
Request Body schema: application/json
required
tool
string

Claude Code tool name: Bash, Write or Edit are checked.

object

command for Bash; file_path and content (Write) or new_string (Edit).

cwd
string
home
string <= 256 characters

The user's home folder on the device, so absolute paths under it match ~ rules. Optional. Ignored unless it is an absolute path. When absent the server guesses it from cwd (/Users/name, /home/name, C:/Users/name).

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 exception_request_id, and the deny text says a request is filed.

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 sdk_call action with the same rules as any other action, using the profile and account of the command that runs the script. Findings can only add restrictions: a deny or ask here applies, and no finding removes a deny the command already earned. The decision row keeps path, hash and matched actions, and a deny reason names the file, for example "deploy.py contains ec2 terminate-instances". Older agents omit the field.

Responses

Request samples

Content type
application/json
{
  • "tool": "string",
  • "input": { },
  • "cwd": "string",
  • "home": "string",
  • "session_id": "string",
  • "client": "claude_code",
  • "client_version": "string",
  • "env": {
    },
  • "profiles": {
    },
  • "request_exception": true,
  • "decision_id": "35405636-5581-4a10-b063-a74afe2ca763",
  • "note": "string",
  • "file_exception_request": true,
  • "script_findings": [
    ]
}

Response samples

Content type
application/json
{
  • "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"
}

Report a decision made while Cortega was unreachable

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.

Authorizations:
deviceToken
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "tool": "string",
  • "session_id": "string",
  • "tool_use_id": "string",
  • "applied": "allow",
  • "on_unreachable": "allow",
  • "reason": "unreachable",
  • "home": "string",
  • "at_ms": 0,
  • "script_findings": [
    ]
}