Kovira API v1

01 · URL architecture

Major group before operation

Every externally consumable endpoint follows /v1/{major-group}/{operation-or-resource}. Group names are lowercase and case-sensitive. Canonical examples omit the terminal slash; a single terminal slash is normalized, but nested suffixes and duplicate separators are rejected.

/v1
├── atlas/                 signed machine inventory
├── calendar/feeds/        opaque-token iCalendar feeds
├── cis/                   configuration items
├── docs/                  this handbook and OpenAPI
├── graphql/query          public GraphQL
├── incidents/             incident records and transitions
├── integrations/          provider-signed callbacks
├── l2/                    network observations
├── platform/health        unauthenticated service liveness
├── scim/v2/               SCIM 2.0 provisioning
└── vector/                signed network discovery

02 · Contract conventions

Predictable on the wire

{
  "data": [{ "id": "…" }],
  "meta": { "next_cursor": null }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid input."
  }
}

Customer API authentication

Create a tenant-bound key in Workspace Settings → API Keys. Send it on REST and GraphQL calls. Keys are hashed at rest, individually scoped, expirable, and revocable.

CopyAuthorization: Bearer kvr_live_REDACTED

03 · Failure semantics

Errors, limits, and retries

Customer keys receive 60 requests per rolling minute. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A separate pre-authentication IP limit bounds credential spraying.

04 · System API

Platform

A lightweight liveness resource for load balancers and external monitors. It checks request handling, not downstream dependency health; operational history remains on the public status page.

05 · Customer REST

Incidents

Incident fields and lifecycle transitions are separate. Use the transition resource for status changes; PATCH handles descriptive and assignment fields.

Enums. Status: new, assigned, in_progress, closed. Priority: p1–p4. Impact and urgency: high, medium, low.

06 · Customer REST

Configuration items

The CMDB list is a unified projection across CI tables. Writes expose a deliberately narrow base shape: type, name, description, status, and customer_id.

Writable types. device, network, service, rack, domain, document, vendor, location, contract, person, group, api, license, software, wan, sla, saas_app, business_service, quote.

Incident/change projections, password records, and integration-managed Entra/Intune records are readable where present but cannot be mutated through generic CI routes.

07 · Customer REST

Layer 2 observations

Read-only operational data produced by VECTOR’s signed ingest pipeline. The public key never receives write access to observation tables.

08 · Customer GraphQL

GraphQL query surface

Queries cover incidents, problems, changes, service requests, CIs, customers, and audit entries with Relay-style connections. Resolvers enforce field-domain scopes. Query depth is capped at eight and production introspection is disabled.

Mutations are createIncident, addIncidentComment, and transitionIncident. Each accepts an optional idempotencyKey; failures are returned as typed mutation-union members.

Copy{
  "query": "query { incidents(first: 10) { edges { node { id number title status } } pageInfo { hasNextPage endCursor } } }"
}

09 · Identity provisioning

SCIM 2.0

Use the dedicated SCIM bearer issued by Kovira. SCIM resource media types and error shapes follow RFC 7644. The product major and SCIM protocol major remain visibly separated in the path.

10 · Signed agent API

ATLAS

ATLAS 0.6.16 uses only the lowercase /v1/atlas group and wire-signature version 4. Registration binds a persistent Ed25519 identity; every operational call must prove both possession of the workspace agent secret and the registered device private key. An ATLAS route accepts only an ATLAS-typed API key bound to that exact device registration; VECTOR keys and registrations are rejected before dispatch.

Enrollment ceremony

An operator explicitly issues an ATLAS-only API key and a separate 15-minute, single-use kovira_enroll_… capability. Kovira stores only SHA-256 digests. The first /v1/atlas/register call must HMAC-sign the request with that exact API key and prove the submitted Ed25519 private key. Capability consumption, live-key revalidation, collision checks, and identity registration commit in one database transaction; any failure consumes nothing. Interactive deployment uses hidden prompts, while automation accepts two newline-delimited secrets on stdin. Secrets are never placed in URLs or process arguments.

Wire v4 request

v4:{METHOD}:{EXACT_PATH_AND_QUERY}:{UNIX_SECONDS}:{NONCE}:{MACHINE_ID}:atlas:{SHA256_BODY_HEX}

Send X-API-Key, X-Machine-Id, X-Timestamp, X-Nonce, X-Signature, X-Sig-Version: 4, X-Signed-Path, X-Agent-Kind: atlas, X-Identity-Proof, and X-Agent-Version. Telemetry also sends X-Schema-Version: 5. The signed path includes the query string byte-for-byte. API keys use exactly kovira_ plus 64 lowercase hexadecimal characters; timestamps are exactly ten decimal epoch-second digits, and HMAC signatures are exactly 64 lowercase hexadecimal characters.

11 · Signed agent API

VECTOR

VECTOR 0.6.16 uses the same wire-v4 primitives, with vector in the group, kind header, and canonical message. Secret-bearing SNMP results are returned only after the central registered-identity gate. A VECTOR route accepts only a VECTOR-typed API key bound to that exact device registration; ATLAS keys and registrations are rejected before dispatch.

Enrollment ceremony

VECTOR uses its own typed API key and 15-minute, single-use enrollment capability. First registration proves the submitted Ed25519 key, binds the X25519 peer identity, and atomically consumes the capability against the exact tenant, customer, key, kind, and machine tuple. Rotation proves the currently registered Ed25519 key. Interactive deploy prompts without echo; secret-manager automation uses the two-line --credentials-stdin contract, keeping both values out of shell history, URLs, and argv. Deploy completes signed registration before installing the service; the enrollment capability is zeroized after the request and is never persisted to config or the OS keyring.

Wire v4 request and response

v4:{METHOD}:{EXACT_PATH_AND_QUERY}:{UNIX_SECONDS}:{NONCE}:{MACHINE_ID}:vector:{SHA256_BODY_HEX}

resp-v4:{REQUEST_SIGNATURE}:{NONCE}:{STATUS}:{CANONICAL_CONTENT_TYPE}:{SHA256_RESPONSE_BODY_HEX}

Successful signed responses include X-Response-Sig-Version: 4 and X-Response-Signature. Agents verify status, content type, and body before consuming the response.

12 · Provider callbacks

Integrations

These are provider-to-Kovira callbacks. Authentication is provider-specific: Stripe signature, Slack signing secret, or Microsoft Bot Framework identity. Public API bearer keys are not accepted.

13 · Token feeds

Calendar feeds

Do not put feed URLs in logs, analytics, support screenshots, or public documents. Rotate a feed token when it may have been disclosed.

14 · Working examples

Start with discovery

Copycurl --fail-with-body https://api.kovira.app/v1

List open high-priority incidents

Copycurl --fail-with-body \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  'https://api.kovira.app/v1/incidents?status=in_progress&priority=p1&limit=25'

Create an incident

Copycurl --fail-with-body -X POST \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Core switch unreachable","impact":"high","urgency":"high","source":"monitoring"}' \
  https://api.kovira.app/v1/incidents

Continue a cursor page

curl --get \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  --data-urlencode 'cursor=RETURNED_OPAQUE_CURSOR' \
  https://api.kovira.app/v1/cis

For SDK generation, use the complete 60-operation contract at https://api.kovira.app/v1/docs/openapi.yaml.

15 · Lifecycle

Versioning policy

The path major is the compatibility boundary. Agent wire and payload schema versions are independent, explicit subcontracts: current ATLAS/VECTOR wire version is 4; current ATLAS telemetry schema is 5.

16 · Integration checklist

Before enabling production traffic

1. Pin the base origin to https://api.kovira.app/v1; do not derive internal /api paths.
2. Grant the smallest required scopes and store keys in a secrets manager.
3. Set connection and response deadlines; retry 429 and transient 5xx with jitter.
4. Only retry mutations when the operation is idempotent or carries a GraphQL idempotency key.
5. Log X-Request-ID, status, and stable error code—never credentials or calendar tokens.
6. Treat cursors as opaque and validate Kovira-API-Version in integration tests.