Authentication

Every request to https://api.illumina.sh authenticates with a bearer token:

curl "https://api.illumina.sh/v1/default/namespaces" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"

API keys

Workspace API keys start with sub_live_ and are minted from the dashboard at app.illumina.sh. The full key is shown once at creation, so store it in a secret manager. Keys are hashed at rest, and you can revoke one from the dashboard at any time.

Free workspaces can hold up to 5 API keys; pro workspaces raise the cap.

Namespace scoping

A key can be scoped to a subset of the workspace's namespaces. Scoping is enforced on every transport, REST and MCP alike:

• A request against a namespace outside the key's scope answers 404, not 403. Existence never leaks across scopes.
• Namespace listings are filtered to the key's scope.
• A scoped key cannot create namespaces. Use an unscoped key (or the dashboard) to bootstrap namespaces, then hand agents a scoped key.

The URL shape

Paths look like /v1/default/namespaces/{namespace_id}/.... The default segment is a fixed literal: your workspace identity comes from the API key, not the URL. Namespace ids are yours to choose (demo, support-agent, team-payments).

Request hygiene

• Send the key only in the Authorization header, never in a query string.
• Rotate keys by minting a replacement, migrating traffic, then revoking the old key.
• Scope one key per agent or integration so a leak has a small blast radius.