Core administration API

​

Authentication

• Core compares the SHA-256 of the bearer with the Core key digest it reads at startup from generated/core-key-digests.json, which oac apply derives from secrets/core.key (Core key). A rotated Core key takes effect when Core restarts. Core serves no /core/v1 route when no digest is configured.
• The Core key authenticates only /core/v1. Project API keys and machine credentials get 401 here, and the Core key gets 401 on /v1 and /api/v1 (API namespaces and credentials).
• X-Core-Console-Actor is a label the caller asserts. Core records it as the audit actor_label without checking it. The console server sends console; scripts normally send none, which records an empty label. Never use it for authorization or as proof of origin.
• A {project_id} in a path selects the target Project, including an archived one; it grants nothing.

​

Routes

​

Projects and keys

• A Project has id, name, created_at, nullable archived_at and active_key_count. A key has id, project_id, name, prefix, created_at and nullable revoked_at. IDs are server-generated UUIDs.
• Project names have 1–128 characters and key names 1–80; names are labels and may repeat, and control characters are rejected.
• Lists order by ID with order=asc|desc (default desc), limit=1..100 (default 20) and after.
• Only the issuance response contains the key’s plaintext, in key; Core stores its digest. Show it once and never cache it. After an uncertain issuance response, list the keys and revoke any you cannot use before issuing another.
• Archive marks the Project archived, revokes all its keys and writes the audit entry in one transaction. Issuing a key in an archived Project returns 409 project_archived. There is no Project deletion, unarchive or key reset.

​

Resource reads and deletion

• Administrator deletion never cancels work: a Session that /v1 could not delete, because a Turn or input is pending, returns the same 409.
• Deleting a Credential removes Core’s copy only; it does not revoke the authorization at the provider.
• HEAD on Skill and Artifact content, a Runtime observation, the Runtime observation list and Runtime history returns 405, so it never samples a provider or queries telemetry.
• Administrator deletions appear in the audit log, not in key write history.

​

Session archive

​

Execution configuration

{
  "object": "agent.session.execution_configuration",
  "schema_version": 1,
  "session_id": "013773a9-44b9-4f84-baca-b51c04a01201",
  "model": {"value": "requested-model", "source": "session"},
  "harness": {"value": "codex", "source": "agent"},
  "harness_config": {"value": {"model_reasoning_effort": "high"}, "source": "agent"},
  "model_provider": {
    "source": "agent",
    "status": "available",
    "configuration": {"protocol": "responses", "base_url": "https://model.example/v1", "api_key_configured": true}
  }
}

​

Installation facts

• path: the absolute host path of config.json, by default ~/.oac/core/config.json;
• apply_command: the command that applies changes, by default ~/.oac/core/oac apply;
• applied_at: when the snapshot was last applied;
• settings: one entry per setting, with its dotted key, applied value, default, whether it is changeable after installation, whether it is sensitive, and the services it restarts (core, web, database).

​

Write provenance

• A write is recorded when it commits. Session input counts once admitted, including input reserved for an Environment that is still preparing; a later execution failure or a lost response does not remove the record. An explicit empty input batch and a repeated creation or deletion are recorded without changing ownership.
• An Environment file upload is recorded when the Runtime confirms the write. Core saves the key, request and trace before sending the file, and records only confirmed uploads.
• Creating a resource also records its creation owner. Updates, retries and no-op writes never change it. A new Skill’s first version and a new Session’s Environment share the creating operation. Artifacts come from the Runtime and have no creation owner; deleting one is recorded.
• Revoking a key stops new writes but keeps its history. Deleting a resource keeps its creation owner and operation history.
• Each record holds its ID, time, key metadata, action, resource type and ID, parent ID, request_id and trace_id. request_id is server-generated per request; a shared trace_id is not an idempotency key. Records never hold request or response bodies, secrets, model credentials, tokens, file paths or file contents.

{"data":[
  {"resource_id":"id1","api_key":{"id":"key-uuid","name":"SDK","prefix":"pc_example","kind":"issued","revoked_at":null},"source":"api_key","admin_audit_id":null},
  {"resource_id":"id2","api_key":null,"source":null,"admin_audit_id":null}
]}

​

Summary

• A key group counts each Session under the key that created it, even when another key later sends input. Sessions without a recorded creator form a group with a null key_id.
• A Session whose public usage is null adds no tokens but counts in the coverage denominator.
• Each Project is read in one database snapshot; a page is not one snapshot of the whole deployment. Totals are operational counts, not billing records.

​

Runtime observations

​

Audit log