Authentication and API keys

Every request carries one header:

Authorization: Bearer sk-sf-...

Getting a key

Your Organization Owner creates keys in the portal: Developer → API keys. The secret is shown once — store it in a secrets manager, never in code.

Three decisions are made at creation time:

1. Project. A key belongs to one project. It sees that project's agents and knowledge, and its usage is attributed there.
2. Scopes. What the key may do: chat, embeddings, rag.read, rag.write, agents.run, workflows.run, usage.read, … A call outside the key's scopes is refused with Key lacks scope(s): ….
3. Model allowlist. The models this key may call. GET /v1/models returns only these, and calling anything else returns key_model_access_denied. Set the allowlist when you create the key — changing it later requires rotating it.

Workflow binding

Workflow runs have one extra lock: the key must be explicitly bound to each workflow it may start (portal → API key → workflow allowlist). A key with the workflows.run scope but no binding is still refused — deny-by-default.

Good practice

• One key per application or environment — rotation then never breaks neighbours.
• Rotate from the portal; the old secret dies the moment the new one is issued.
• Disabled or compromised keys are blocked at the gateway within a minute.