Core API

Authentication and API key handling for Contro1

Secure your Contro1 integrations with environment-based API keys, role-aware routing, and clear ownership boundaries.

Authentication is simple on the wire, but safe key storage and route ownership are what make the integration production-ready.

Key takeaways

  • API keys authenticate the caller; required_role gates who can answer.
  • Rotate keys on ownership changes; test and production keys must be separate.
  • Webhook signing uses a shared secret distinct from the API key.
  • Team boundaries are enforced server-side - a key only sees its own organization.

Base authentication pattern

headers.txt
Authorization: Bearer cc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Security rules

  • Store API keys in server-side environment variables, never in browser code.
  • Rotate keys when ownership changes.
  • Separate test and production keys.
  • Use webhook secrets for callback verification.

Team ownership

API authentication proves the app can create requests, while required roles and operator permissions decide who is allowed to answer them.

API keys can also carry default routing. When a request response shows routing_source: "api_key_default", the request used the routing configured on that key in Settings -> APIs & Webhooks. A request-level routing field can override the default when your integration needs a different team or role.

Frequently asked questions

Can different teams use different keys?

Yes. Many organizations separate environments, internal tools, or business domains with different keys and routing policies.

What happens if a key leaks?

Rotate immediately in Contro1 settings. Requests created with the old key continue to callback normally, but no new requests can be created with it.

How do I test safely?

Use a cc_test_ prefixed key against a staging workspace. Callbacks are real HTTP but operator decisions are isolated from production queues.