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 sessions created by a different API key (session ownership is tied to the creating principal).

• 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 ownership

When an agent key creates a session, that session is owned by the key. Only the owning key – or a management key – can append turns to it. This prevents one agent from injecting turns into another agent's conversation history.

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

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 "API-KEY: $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