Govern
API keys
An API key is a credential a worker, continuous integration job, or backend service uses to authenticate to Mobius.
The key is not the workload's identity or permission set. It belongs to an API client, and that client's roles decide what the workload can do. Keeping those concepts separate makes rotation and access changes much easier to reason about.
Identity, credential, and access
| Concept | Question it answers |
|---|---|
| API client | Which workload is acting? |
| API key | How did it authenticate? |
| Role | What may it do? |
Create one API client per workload, such as a production worker or deployment service. Add a second key to the same client when rotating its credential. Create a new client when the workload or access boundary is different.
Prefer project keys
Most workloads belong to one project. A project key keeps the credential and its permissions inside that boundary, which limits accidental access and makes audit history easier to understand.
Use an organization-level key only when one administrative service genuinely needs to operate across projects. It is a broader credential, not a convenient default. Workers and project-pinned model routes use project credentials.
Organization-level keys
Organization-level keys are for the small number of administrative services whose responsibility genuinely spans project boundaries. Give them the least privileged organization role that still does the job and keep them out of project workers and model routes.
Choose access for the workload
Start with the narrowest system role that matches the job:
| Workload | Typical role |
|---|---|
| Worker that performs customer-hosted work | Worker |
| CI or operator service that starts and cancels runs | Operator |
| Read-only dashboard or alerting service | Viewer |
| Service with one unusual responsibility | Narrow custom role |
Reserve broad administrative roles for people. If a workload grows a new responsibility, change the role on its API client rather than sharing another service's credential.
Create and rotate keys in the app
Open Settings > Access, choose or create the API client that represents the workload, then create a key from that client.
Mobius shows the full secret once. Store it in the deployment's secret manager immediately. The app keeps a safe prefix so you can identify the credential later without exposing it.
For rotation, create a second key on the same API client, move the workload, confirm the new key is in use, then revoke the old one. The client's roles and audit identity remain stable throughout the change.
Keep credential boundaries clear
- Use one API client per workload and separate keys per deployment path.
- Give temporary test or continuous integration credentials an expiry.
- Revoke unused keys and disable the client when the whole workload is retired.
- Do not share API keys between people. Human users should authenticate as themselves so audit records preserve individual responsibility.
The Create an API key guide walks through the app flow. Install and authenticate covers using a key with the CLI or worker. The Access-control API owns the exact key and principal contract.
Next
- Create the workload identity with API clients.
- Choose permissions with roles.
- Trace machine activity with audit logs.