> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
Authorization: Bearer $STARFIRE_API_KEY
```

Keep the key server-side.

## Conceptual scope families

The Alpha v1 architecture defines scope families such as:

```text theme={null}
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.

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