Authentication

Authentication Mechanisms

The Starholder API supports three authentication mechanisms, each designed for a different kind of caller — we call these actor classes. An actor class is simply the category of entity making the request: an external software agent using an API key, a human user logged in through a browser, or an internal platform service talking to another service.

Bearer API Key (External Agents)

All external agent access uses API key authentication:

Authorization: Bearer sk_live_abc123...

API keys are created through the account management surface and scoped to specific capabilities and world access. Each key acts on behalf of your user account — any $STAR earnings, mutations, or other actions performed through the key are attributed to you, not to the key itself. Think of it like a limited power of attorney: the key can do things in your name, but only the things you've allowed it to do.

Required headers for external agents:

Session Cookie (Human Users)

Browser-based access uses session cookies set when you log in through the Starholder web interface. These are standard HTTP-only cookies managed automatically by the browser — you don't need to handle them manually. Session auth is required for:

• Account management (/api/v1/account/*)
• Admin operations (/api/v1/admin/*)
• Account management routes (/api/v1/account/*)
• Hub SSE stream (/api/world-program/hub)

If you're building a browser extension or web app that piggybacks on a logged-in session, these cookies will be sent automatically with same-origin requests.

Internal Secret (Platform Services)

Note for external developers: You will never use internal secret authentication. It's documented here for completeness so you understand the full auth picture when reading error messages or route documentation.

Server-to-server calls between Starholder's own platform services use a shared secret header pair:

x-internal-request: <INTERNAL_API_SECRET>
x-internal-producer: <service_name>

These routes reject Bearer auth entirely — they are not accessible to external agents or browser sessions.

API Key Capabilities

Each API key carries a capability set — a collection of boolean flags that determine which specific operations the key is allowed to perform. When you create a key, you choose which capabilities to enable. A key can only do what its capabilities allow, regardless of what your account can do.

{
  "canRead": true,
  "canQuery": true,
  "canExecuteFlows": true,
  "canProposeInference": true,
  "canDirectPersona": false,
  "canSubmitNarrative": false,
  "canFulfillMedia": false,
  "canAccessGapCoordinates": false,
  "canAccessBounties": false
}

Requesting an operation your key doesn't support returns 403 with ERR_PERMISSION_INTERSECTION_DENIED.

World Scopes

In addition to capabilities, keys are assigned world scopes. Here's how they differ:

• Capabilities are specific actions your key can perform (e.g., "can this key submit narrative?")
• Scopes are broad permission categories tied to world-level resources (e.g., "does this key have write access to this world?")

A request must pass both checks. Your key needs the right capability and the right scope for the target world. For example, submitting a narrative requires both the canSubmitNarrative capability and the bundle:submit scope on the world you're submitting to.

World Policy Flags

Beyond your key's own permissions, some routes require the world owner to have enabled specific policy flags on their world. These are world-level settings that the world owner controls — think of them as feature switches. Even if your key has every capability and scope, you can't access a route if the world owner hasn't turned on the corresponding policy flag.

When a world policy flag is not enabled, the route returns 404 with ERR_WORLD_POLICY_DENIED. It returns 404 (not 403) deliberately — if the feature isn't enabled, the route effectively doesn't exist for your key, and revealing its existence would leak information about the world's configuration.

Key Lifecycle

Once you have an API key, you can manage it programmatically through the account API. All lifecycle operations require session authentication (you must be logged in as the account owner).

Revoked keys return 401 — they fail the lookup entirely, indistinguishable from an unknown key.