Principals

A principal is the identity associated with an API key. Spectron has three principal types. Each has a different scope floor and a different set of permitted operations.

Management principal

A management key is created with spectron init --admin-key (first key) or via the management API using an existing management key. Its scope floor is {} – the empty set, meaning it is not restricted to any particular org, agent, or user.

Management keys are for operators and provisioning pipelines. Application-level agents must not hold management keys.

Capabilities:

• Full read and write access to all data within a Context, regardless of scope.

• Create, update, and delete Contexts.

• Create, list, and delete API keys of any principal type.

• Read and write all sessions, turns, entities, attributes, relations, and knowledge nodes.

• Access decision traces and audit logs.

• Modify Context configuration (models, providers, token limits, ontology).

Restrictions:

• Management keys are scoped to the Spectron deployment, not to a specific Context. A management key for one deployment cannot access a different Spectron deployment (separate binary + SurrealDB).

Agent principal

An agent key is created via the management API. Its scope floor is pinned to a minimum of {org, agent}, with an optional user field. Once set, the scope floor cannot be widened – the key will never be able to access data outside the org and agent it was created for.

Agent keys are the principal type used by deployed AI agents, application backends, and SDK clients in production.

Capabilities:

• Create and append to sessions within the scope floor.

• Add turns to sessions that the key created.

• Recall memory and retrieve context scoped at or below the key's floor.

• Upload documents and create knowledge nodes within the scope floor.

• Access profiles for entities visible within the scope floor.

Restrictions:

• Cannot read sessions, turns, entities, or knowledge nodes outside the scope floor.

• Cannot create or delete API keys.

• Cannot modify Context configuration.

• Cannot append turns to a session whose scope falls outside the key's memory:write region (see Creating sessions).

• Cannot read general knowledge (scope {}) – only management keys can write general knowledge, though agents can read it during recall (Spectron's resolution pipeline includes general knowledge automatically in recall results where relevant).

Session write access

When an agent pins an existing session_id on /facts, /facts/batch, or /chat, Spectron checks that the session's scope lies within the caller's write region. Guessing another principal's session id does not grant write access.

Supervisor principal

A supervisor key sits between management and agent. Its scope floor is {org} – it can read across all agents and users within an org, but cannot write to most resources.

Supervisor keys are for monitoring tools, auditing dashboards, and reflection pipelines that need a read view across an entire org without having write access.

Capabilities:

• Read sessions, turns, entities, attributes, and relations within the org scope.

• Read decision traces for all requests within the org.

• Read profiles for all entities within the org.

• Write reflection insights (higher-level synthesised facts) scoped at the org floor.

Restrictions:

• Cannot create sessions or add turns.

• Cannot create or delete API keys.

• Cannot modify Context configuration.

• Cannot write entities, attributes, or relations – only reflection insights.

Endpoint access control matrix

Creating principals

Principals are created on the management API. A data-plane Context key cannot mint new principals.

CLI:

spectrond principals create demo "Planner bot" \
  --kind agent \
  --grant memory:read=team/eng \
  --grant memory:write=team/eng \
  --url "$SPECTRON_MANAGEMENT_URL" \
  --api-key "$SPECTRON_MANAGEMENT_API_KEY"

# thin client — reads SPECTRON_MANAGEMENT_URL, SPECTRON_MANAGEMENT_API_KEY, SPECTRON_CONTEXT_ID
spectron principals create "Planner bot" --kind agent -c demo \
  --grant memory:read=team/eng --grant memory:write=team/eng

Flags: --kind (human | agent | service | unknown, default agent), repeatable --grant <noun>:<verb>=<scope-pattern>, optional --external-id for idempotent create-or-get. The server returns {"id": "…"} — mint a data-plane key for that principal via the management API.

HTTP:

POST /api/v1/contexts/{context_id}/principals
Authorization: Bearer <management-key>
Content-Type: application/json

{"display_name": "Planner bot", "kind": "agent"}

See Management API — principals for grants and key minting.

Viewing key metadata

You can retrieve the principal type and scope floor for any key without exposing the secret:

curl -s https://spectron.example.com/api/v1/contexts/acme-prod/keys \
  -H "Authorization: Bearer $SPECTRON_MANAGEMENT_API_KEY"

[
  {
    "name": "planner-agent",
    "principal": "agent",
    "scope_floor": { "org": "acme", "agent": "planner" },
    "created_at": "2025-11-04T14:00:00Z",
    "expires_at": null,
    "revoked_at": null
  },
  {
    "name": "ops-supervisor",
    "principal": "supervisor",
    "scope_floor": { "org": "acme" },
    "created_at": "2025-11-04T14:05:00Z",
    "expires_at": "2026-01-01T00:00:00Z",
    "revoked_at": null
  }
]

Next steps

• Authentication – creating and rotating keys

• Scope as a security boundary – how scope floors are enforced

• Multi-tenancy – patterns for isolating tenants