Authentication

Every request to the Holocron API is authenticated with an API key. Keys are scoped to a single project, so the key alone tells Holocron which project you are acting on; you never pass a project ID separately.

API keys look like holo_xxxxxxxx. Send yours as a Bearer token in the Authorization header on every request:

12curl https://holocron.so/api/v0/projects \
  -H "Authorization: Bearer holo_xxxxxxxx"

The same key works across the whole API: the management endpoints (/api/v0/projects, /api/v0/me), the deploy pipeline (/api/v0/deployments), and the AI chat gateway (POST /api/chat). A key only ever acts on its own project; it cannot read or modify other projects in your org. Creating new projects and managing API keys requires signing in with the CLI or dashboard.

Treat API keys like passwords. Never commit them to git or embed them in client-side code. Read the key from an environment variable on the server, and create a separate key per environment so you can rotate them independently.

Get an API key

You can create a key two ways: from the CLI or from the holocron.so dashboard. Both produce the same holo_xxx key.

From the CLI

First authenticate the CLI once with the device flow (opens your browser):

1npx -y @holocron.so/cli login

If you do not have a project yet, create one:

1npx -y @holocron.so/cli projects create --name "My Docs"

Then create a key scoped to that project. Run keys create without --project to pick from a list, or pass the project ID directly:

1npx -y @holocron.so/cli keys create --name production --project <projectId>

The command prints the key once. Copy it immediately; it is not shown again.

List existing keys with npx -y @holocron.so/cli keys list and revoke one with npx -y @holocron.so/cli keys delete <keyId>.

From the holocron.so dashboard

Sign in at holocron.so, open your project, and go to its API keys section. Create a key, give it a name (for example production), and copy the holo_xxx value. The key is scoped to that project automatically.

Use the key

Pass the key on every API call. The example below lists your projects:

1234export HOLOCRON_KEY=holo_xxxxxxxx

curl https://holocron.so/api/v0/projects \
  -H "Authorization: Bearer $HOLOCRON_KEY"

The same HOLOCRON_KEY environment variable is also what the CLI and CI use to deploy without an interactive login. See Deploy to Holocron for the full deploy flow.

The rest of this section is the full endpoint reference, generated from the OpenAPI specification.

Ask AI about this page