Secrets & Keys

AI features need credentials to call external LLM providers. In Causet Cloud, you configure these through bring-your-own-key (BYOK) in the control plane — encrypted at rest, scoped per fork, and never written into your .causet files or compiled artifacts.

What keys you need

Which credentials to configure depends on what your spec declares under providers:.

If your app uses both decisions and vector memory with OpenAI, you typically need one OpenAI key that covers both the reasoning and embeddings logical providers (they can share the same executor).

Keys you do not put in the spec

Your .causet files declare what to call, not how to authenticate:

# providers/ai.providers.causet — no secrets here
providers:
  reasoning:
    executor: openai
    model: gpt-4o-mini
  embeddings:
    executor: openai
    model: text-embedding-3-small

Compile output (causet.decisions.json) contains provider configuration only — model names, temperatures, prompt refs. API keys are resolved at runtime from fork secrets.

Setting up keys in Causet Cloud

1. Open application settings

In the control plane:

Platform → Application → Settings → AI Providers

Select the fork (main by default, or a staging fork). Each fork has its own credential slots — production and staging keys stay isolated.

2. Add provider credentials

For each executor your spec uses (openai, anthropic, ollama), you see two scope rows:

Click Set key (or Rotate to replace an existing key). Paste the provider API key in the modal. The value is encrypted immediately and only a masked status is shown afterward.

3. Deploy a release that defines AI sections

Keys alone are not enough — the fork must have an active release whose spec includes providers, decisions, and/or memories. Compile and activate the release as usual.

4. Enable vector memory (if used)

If your spec defines memories:, ensure your plan includes AI memory and that the embeddings provider has a configured key. Ingestion runs asynchronously after ledger commits and calls the embeddings provider for each matching source event.

How the runtime resolves credentials

When a decision or memory embedding call runs, the runtime looks up credentials in this order:

1. Application BYOK — application-scoped fork secret for this executor
2. Fork-wide BYOK — fork-scoped secret for this executor
3. Platform environment fallback — OPENAI_API_KEY (self-hosted / operator-configured)

Application-scoped keys win over fork-wide keys. BYOK always wins over environment fallback when present.

The control plane pushes secrets to the runtime over an internal channel when you save or rotate a key, so new credentials take effect without redeploying your spec.

Encryption and rotation

• Keys are stored encrypted at rest (AES-256-GCM) in the control plane database.
• Saving a key creates or rotates a versioned fork secret; the UI shows version and last-updated time.
• Remove deletes the encrypted secret; AI calls for that executor fall back to the next source in the resolution order.
• Secret changes are audited (who rotated, when, which fork).

You cannot view a saved key after entry — only rotate or remove. Treat the control plane like any secrets manager: store the canonical key in your password manager or vault.

Local development without keys

For tutorials, playground, and CI, use the mock executor — no API key required:

providers:
  reasoning:
    executor: mock
    model: mock-model
  embeddings:
    executor: mock
    model: mock-model

Mock returns schema-valid placeholder output so the full decision → emit → listener pipeline runs without external calls.

API keys vs provider keys

These are different credentials for different purposes:

Causet API keys authenticate your application when submitting intents or querying read models. They are not passed to LLM providers.

Generate Causet API keys in Settings → API Keys, scope them to the application, and use them as Authorization: ApiKey <key> (or Bearer JWT from Clerk for user sessions). Rotate and revoke keys from the same screen.

Checklist before going live

• Every executor in your spec (except mock) has a fork-wide or application key configured on the production fork
• Embeddings provider has a key if you use memories:
• Active release includes causet.decisions.json
• No API keys in git, .causet files, or IR artifacts
• Staging fork uses staging provider keys (not production keys)
• Causet API keys for server-to-server intent submission are issued and stored in your app’s secrets manager

Troubleshooting

Use the Decision Log to inspect failed decision steps — auth errors appear before output validation.

Self-hosted runtime

If you run the runtime yourself (not Causet Cloud), configure provider credentials via environment variables such as CAUSET_OPENAI_API_KEY or OPENAI_API_KEY, and use the same fork-secret mechanism if CAUSET_SECRETS_MASTER_KEY is configured. See Secrets Management for infrastructure credential patterns.

See also

• Providers & Prompts — declaring logical providers and prompts
• Defining Decisions — op: decision runtime behavior
• Vector Memory — embeddings provider for ingestion
• Best Practices — mock executor, CU cost, schema design