> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Use API keys, short-lived bearer tokens, scopes, and request correlation with Kyberis.

Kyberis supports two machine authentication modes.

## API Key Credentials

Most investigation endpoints accept API key credentials:

```http theme={null}
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:

```bash theme={null}
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:

```http theme={null}
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`.

```json theme={null}
{
  "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:

```http theme={null}
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`.