Authentication

Kyberis supports two machine authentication modes.

API Key Credentials

Most investigation endpoints accept API key credentials:

Authorization: ApiKey <key_id>:<secret>

Keep API key secrets out of prompts, logs, screenshots, and committed files.

Short-lived Bearer Tokens

Mint a bearer token from API key credentials:

curl -sS -X POST "https://api.kyberis.ai/v2/auth/token" \
  -H "Authorization: ApiKey <key_id>:<secret>" \
  -H "Accept: application/json"

Use the token on bearer-protected endpoints:

Authorization: Bearer <access_token>

Bearer token responses include expiry, scopes, audiences, issuer, principal ID, and token type. Rotate back to API key credentials when a bearer expires instead of storing bearer tokens long term.

Scopes

Different endpoints require different scopes. Common examples:

Scope	Used for
`read:resolution`	Entity resolution and entity hydration
`read:evidence`	Evidence retrieval and evidence hydration
`read:relationships`	Relationship pivots
`read:intel`	General intelligence search
`read:prioritize`	Environment-aware ranking
`read:hunt_pivots`	Hunt pivot recommendations
`read:assessments`	Deterministic assessment endpoints
`batch:*`	Batch variants of the read endpoints

A missing scope returns 403 with error_code="insufficient_scope" and required_scopes.

Agent Context

All investigation POST calls should include agent_context.

{
  "agent_context": {
    "objective": "Determine whether this alert is actionable.",
    "requested_outcome": "Return evidence-backed guidance.",
    "workflow_stage": "assessment",
    "run_id": "run-20260527-001",
    "step_id": "step-03"
  }
}

Allowed workflow stages are resolve, evidence, relationships, assessment, hunt, hydrate, batch, finalize, and other.

Hydration Headers

GET /v2/entities/{canonical_id} and GET /v2/evidence/{evidence_id} use headers for agent context:

X-Agent-Objective: Hydrate the entity for final reporting.
X-Agent-Requested-Outcome: Return bounded detail.
X-Agent-Workflow-Stage: hydrate
X-Agent-Run-ID: run-20260527-001
X-Agent-Step-ID: step-04

Request Correlation

Send X-Request-ID when you need cross-system tracing. Kyberis responses include X-Request-ID; error bodies also include request_id.

⌘I

Getting started

Install Kyberis

Threat investigations

Sample investigations

Interpret responses

API Key Credentials

Short-lived Bearer Tokens

Scopes

Agent Context

Hydration Headers

Request Correlation

​API Key Credentials

​Short-lived Bearer Tokens

​Scopes

​Agent Context

​Hydration Headers

​Request Correlation

API Key Credentials

Short-lived Bearer Tokens

Scopes

Agent Context

Hydration Headers

Request Correlation