Skip to main content
Everything you build with Octavia belongs to a team, and every call is made with an API key that belongs to that team. This page explains how those two fit together, and which key to use where.
Creating and rotating keys happens in the dashboard. This page explains the model behind it. For the click-by-click version, see API keys.

​
Teams

A team is the unit of isolation. Its members, its API keys, its content, and its usage are all separate from every other team’s. Your first team is created for you at sign-up, named after you. From the team switcher in the dashboard you can create more, and you can have keys and apps in several at once.
Keys are scoped to a team and a service. A key you create for Storage never counts against your AI CMS key allowance, and you can revoke one without touching the other.

​
Roles

Roles come in two flavours, and it is worth keeping them apart. User roles decide what a person can do in the dashboard — invite teammates, manage billing, rotate keys. Key roles decide what a credential can do against the API. This is the list that matters when you are writing an integration:
A key that authenticates successfully can still be rejected with 403 if its role lacks permission for that operation. Authentication and authorization are separate checks — a valid key is not automatically a permitted one.
Start at the lowest role that covers the use case and raise it when a call actually fails with 403. Most public-facing reads never need more than Read-only.

​
Choosing a key for a job

The most useful thing you can do is give each system its own key. Then a leak, a rotation or a mistake is contained.
Keys can be given an expiration date or a lifetime with no expiry, and can be disabled and re-enabled without being deleted. See API keys.

​
Keeping a key safe

A key in client-side code — a browser bundle, a mobile app, a public repository — is a compromised key. Call Octavia from your server only.
  • Read it from the environment. Never hardcode it.
  • Never commit it. Keep it in your deployment platform’s secret store.
  • Rotate on a schedule, and immediately if it is ever exposed.
  • Use the dashboard’s last-used timestamps to find keys nothing is using any more, then revoke them.
Disabling a key takes effect immediately across every client using it, so rotate before you revoke when a running service depends on it.

API keys

Create, edit, disable and revoke keys in the dashboard.

Authentication

How the key is sent, and how multi-tenancy works.