Security overview
This page explains who can do what on the Crusoe Agent Platform — and, just as importantly, who cannot. If you read one security page, read this one.
A story: Sam, Ava, and the locked room
Sam is a project admin on ml-team. Her project holds an agent, its logs, and a secret with a customer database password.
Ava is a platform admin — she works for the provider and operates the platform itself. Ava can see that ml-team exists. She can rename it, delete it, or add a new member. But when Ava calls the API for Sam's agents or secrets, she gets 404 not found — the same answer a total stranger would get. Not "forbidden." Not found. As far as the contents of ml-team are concerned, Ava does not exist.
One day Sam's project is broken and she asks for help. Ava cannot quietly peek inside. Her only way in is break-glass: she grants herself temporary membership, must write a reason of at least 8 characters that Sam's whole team will read verbatim, the grant expires on its own (4 hours by default, 24 at most), it shows up loudly on the project's IAM page, and it is written to the audit log Sam's team can read forever. See break-glass and audit.
That story is the whole model. The rest of this page names its parts.
The two axes of authority
Authority over a project is split into two independent axes:
- Metadata authority — power over the project object: rename it, delete it, manage its members.
- Resource authority — power over the project's contents: agents, functions, secrets, topics, indexes.
The key fact: a platform admin holds metadata authority everywhere and resource authority nowhere. The provider's staff can administer the shell of every project without being able to open any of them. This is enforced in the API's authorization layer, not by policy documents.
Every project API response tells you where you stand with two fields: your_role (resource axis) and your_metadata_role (metadata axis). A platform admin sees your_metadata_role set to admin and your_role empty — and the console uses exactly that signal to show them IAM pages but hide the contents.
The roles
| Role | Scope | Metadata authority | Resource authority |
|---|---|---|---|
| Platform admin | Whole platform | Everywhere | Nowhere (break-glass only) |
| Org admin | One organization | Every project in the org | Every project in the org (inherited admin, resolved live) |
| Project admin | One project | That project | Full — including deletes, secret reveals, minting credentials |
| Project member | One project | None | Use the project's resources |
| Service account | One project | None, ever | Its granted role, resource axis only |
Two details worth knowing:
- Org-admin inheritance is computed fresh on every request. Demote an org admin and their access to every project in the org is gone on their next API call.
- A service account can never touch membership, accounts, or credentials — even at
admin. A leaked machine key cannot mint its own replacements. See service accounts and API keys.
The 404-vs-403 rule
The platform never confirms the existence of a project you hold no grant on:
- No grant on the project →
404 not found. Always. You cannot probe for project ids or slugs. - Some grant, wrong role →
403. Once you can legitimately see a project, being told "you can't do that" is useful rather than leaky.
So if your script gets a 404 on a path you are sure exists, the first thing to check is not the URL — it is your credential and your membership.
Why this design
The big clouds solve provider access with policy: internal controls, background checks, contractual promises. We solve it structurally: the API cannot express "provider reads tenant data" without creating a visible, expiring, audited grant first. In alpha, with a small team operating the platform, we think a mechanism you can verify beats a promise you have to trust.
How it compares
| Crusoe Agent Platform | AWS IAM / GCP IAM / Azure RBAC | |
|---|---|---|
| Granularity | Two roles per project (member, admin) — deliberately simple | Fine-grained per-action policies; far more expressive |
| Provider staff access | Structurally blocked; tenant-visible break-glass is the only path | Governed by internal provider controls; not visible to you in-product |
| Role changes take effect | Next request (authority is re-read live) | Typically fast, but propagation delays exist |
| Federation, SSO, MFA | Not yet (alpha) | Mature in all three |
In this section
- API authentication — the four credential shapes and how requests are checked
- Break-glass and audit — provider access mechanics and the audit log's guarantees
Summary
- Two axes: metadata (the project object) vs. resource (its contents).
- Platform admins run the platform but cannot read your data; break-glass is the loud, expiring exception.
- No grant means 404 — project existence is not discoverable.
- Authority is re-resolved on every request; demotions and revocations bite immediately.
- Machines (service accounts) can hold resource roles but can never manage credentials or membership.