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.

Machine bearer tokens minted from API keys are not console session tokens. Use the Kyberis dashboard to create, list, update, or delete API keys; the /v2/api-keys management endpoints require a console login session and do not accept API keys or machine bearer tokens.

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. You can include optional agent_context.skill to identify the executing skill:

{
  "id": "ioc-triage",
  "version": "1.0.0"
}

Set id to 1–128 characters. If you provide version, use 1–64 characters; both values reject control characters. Skill metadata is self-reported and does not verify installation or outcomes. You can omit skill without changing existing requests. See Intelligence flow for recorded transport, agent, and skill attribution.

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.

Getting started

Install Kyberis

Platform integrations

Threat investigations

Sample investigations

Interpret responses

API Key Credentials

Short-lived Bearer Tokens

Scopes

Agent context

Hydration Headers

Request Correlation