Authentication & Scope Reference

Reference Starfire AI developer authentication, bearer credentials, scope design, rotation, revocation, and organization ownership.

Authentication & scope reference

Developer credentials identify software workloads. They are separate from interactive browser sessions and should be scoped to the smallest set of operations the integration needs.

Authentication model

Where enabled, Starfire v1 uses dedicated API credentials rather than a person’s browser session.

Authorization: Bearer $STARFIRE_API_KEY

Keep the key server-side.

Conceptual scope families

The Alpha v1 architecture defines scope families such as:

models:read
chat:create
responses:create
runs:create
runs:read
runs:cancel
files:read
files:write
artifacts:read
research:create
research:read
builds:create
builds:read
knowledge:read
knowledge:write
usage:read

The active Developer Portal is the source of truth for the current scope catalog.

Scope design

Grant only what the workload needs.

Examples:

• a model browser can use models:read
• a FORGE backend can need build creation/read and artifact read
• a Knowledge ingestion service can need file/knowledge write without billing administration

Rotation

Create a replacement key, update the dependent service, verify new requests, then revoke the old credential.

Revocation

Revocation should stop new authenticated API requests from that credential independently from the owner’s browser sessions.

Organization ownership

Production keys should belong to an organization/application/service account where supported so offboarding one employee does not break the integration.

Do not log full Authorization headers or API secrets. When debugging, log credential/application identifiers and request IDs instead.