> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corbits.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Organizational guardrails: Credentials & Grants
> How Corbits keeps every agent capability inert until your organization's policies authorize it — the credential and grant model behind enterprise control and audit.
When you run agents across an organization, two questions never stop mattering: what can each agent reach, and who authorized it to reach that. Corbits answers both with one model. Every capability an agent has is inert until an explicit policy turns it on, and every decision to turn it on is a durable record you can inspect.
This page is the control-and-audit reference. If you lead an AI org, it shows you how to hand agents real power without handing over the keys. If you own security or compliance, it shows you where authority comes from, how it is bounded, and why the default is always deny.
The Corbits platform runs on an agent runtime that resolves every credential and authorization decision through a central control plane before an agent does any work. Nothing described here is opt-in hardening — it is how the platform launches agents.
## Two primitives
Everything reduces to two things:
The secrets an agent uses to authenticate with an outside service — an API key, an OAuth token, a certificate. Owned and stored by your organization, never discovered by the agent.
The atomic unit of authorization. Every decision about what an agent may do is resolved by evaluating grants. A capability with no matching grant is denied.
A capability that reaches the outside world needs both. A credential says *how* to authenticate; a grant says *whether* this principal is allowed to use it at all.
## Credentials
A credential is a runtime secret an agent uses to authenticate with a **provider** — GitHub, OpenAI, Slack, Google Drive, an internal deployment service, an SSH bastion. Every credential belongs to a provider; there are no provider-less credentials. The provider definition is what tells the platform how to handle the credential: its refresh behavior, its authentication method, its scope model.
The credential's type — API key, OAuth token, certificate — is a property of the credential, **not** something the agent chooses. From the agent's side, it needs "access to service X," and the platform figures out the authentication mechanism. Agents do not select or negotiate credential types.
### Resolved at launch, never at runtime
This is the principle that makes credentials auditable:
**Agents never discover or look up credentials at runtime.** When an agent launches, the control plane resolves the credentials it needs and hands them to the agent's harness as part of launch. The harness holds them in memory for the agent's lifetime and mediates every use — proxying requests with authentication attached, or injecting the credential into the runtime.
Resolution, access control, and scope validation all happen at launch time. An agent can never reach into a store and pull a secret it was not launched with. Credentials live in the control-plane credential store and are resolved into a specific agent's harness only when that launch is authorized.
Secrets in the credential store are held as plaintext today. Encryption at rest — envelope encryption or KMS integration — is a separate concern the platform does not yet address, so we do not claim it. The guarantee we do make is architectural: credentials are resolved and scoped at launch, and agents never look them up themselves.
### Two independent axes
Credentials vary along two axes that are easy to conflate. Keep them separate.
A credential can optionally be owned by a specific principal in the tenant.
* **Organizational** — no principal owner. Shared across the tenant and managed by administrators. This is the company's OpenAI key, its deploy token.
* **Personal** — owned by a specific user or agent, typically created through an OAuth flow where that user authorized the platform to act on their behalf with a third-party service.
An agent definition declares *which* credential a requirement should resolve to by source:
* `tenant` — the tenant's organizational credential.
* `creator` — the agent author's personal credential.
* `invoker` — the user launching the agent supplies their own.
Source is about provenance of authority, not about sharing. A `tenant`-sourced credential is shared; an `invoker`-sourced one is not. Do not read "shared" as "invoker."
Credentials also carry scopes — populated automatically for OAuth tokens, and specified by an administrator for API keys — so the control plane can match an agent's declared requirements accurately regardless of credential type. If an agent requires a scope the credential does not declare, the credential does not match and the launch does not use it.
## Grants
Grants are the atomic unit of authorization. Every authorization decision is resolved by evaluating grants. A grant carries three fields:
| Field | What it is | Examples |
| ---------- | ------------------------------------------- | --------------------------------------------------- |
| `resource` | A glob pattern for what is being authorized | `tool:bash`, `credential:crd_gdrive`, `tool:*`, `*` |
| `action` | The operation verb | `invoke`, `read`, `use`, `*` |
| `effect` | The decision | `allow`, `deny`, `ask` |
A grant attaches either to a **role** — a named bundle of grants scoped to a tenant, assigned to users and agents — or directly to a **principal**. System roles (owner, admin, member) are created with every tenant; admins can define custom roles on top.
### How a decision is made
For any principal attempting any operation, the engine:
Gather every grant that applies — direct grants on the principal plus grants from all of its roles.
Keep only grants whose `resource` and `action` patterns match the operation.
More specific patterns beat less specific ones — a grant on `credential:crd_gdrive` outranks one on `*`.
The most specific matching grant sets the effect. When two matching grants are equally specific, the most restrictive effect wins: **deny beats ask beats allow**, so ambiguity always resolves toward less access.
If nothing matches, the operation is denied. The system is **fail-closed** by default.
An `ask` effect blocks execution and surfaces an approval prompt to the appropriate human, who can allow it once, allow it always (creating a persistent grant), or reject it. Conditions on a grant — time windows, approval thresholds, rate limits — are evaluated at the same time; a grant whose conditions are unmet is skipped.
Fail-closed is the property compliance cares about most. There is no implicit allow, no ambient authority, no capability that works "because nobody blocked it." Silence is denial.
### Where authority comes from: the three-source model
An agent definition does not ship live grants. It ships **requirements** — a manifest of the capabilities it needs. At launch, the control plane resolves each requirement against real authority and materializes grants on the agent's own principal. Each requirement declares a source:
Your organization's policies must allow it. Resolved from system and role grants, walking **up** the tenant hierarchy. This is the org setting the boundary.
The definition author delegates authority they themselves currently hold. This is the setuid model: the author's authority travels with the definition. A creator cannot delegate what they do not have — the control plane checks at every launch.
The person launching the agent must supply it. Materialized as a short, session-scoped grant that expires when the agent stops.
The agent's **effective** authority is the union of tenant, creator, and invoker grants, each subject to that party's own authorization, all materialized on the agent's principal at launch. Because requirements resolve fresh every launch, revoking a creator's or invoker's authority takes effect on the next launch — and running agents lose affected grants when the control plane pushes an update.
## The thesis: inert without both
A tool is a capability that does nothing on its own.
* A tool is inert without a **grant**. `tool:bash` needs one thing to run: a grant that allows `invoke` on `tool:bash`. No credential is involved.
* A tool that reaches an **external provider** is *additionally* inert without a resolved, grant-authorized **credential**. The credential must resolve at launch, and a grant on `credential:...` with action `use` must authorize this principal to use it.
Not every tool needs a credential — only the ones that touch an outside service. But every capability, without exception, needs a grant.
This is deliberate layering. The platform composes independent authorization layers where **both must allow** the operation, and **the narrower of the two layers always wins**. An agent's effective offerings are exactly the set determined by which credentials *and* which grants were successfully resolved. Broad credential access is worthless without a grant; a grant is worthless without a credential the launch could resolve.
## Tenant hierarchy and inheritance
Authority is organized by tenant.
* A **principal** is an identity within a tenant — the join between an entity (a user or an agent) and that tenant. A principal by itself grants nothing; it only establishes that the entity exists in the tenant.
* A **tenant** is the isolation boundary. It has a nullable `parent_id`, so tenants form a hierarchy of parents and **sub-tenants** (child tenants).
Two things inherit down this hierarchy, and they inherit with opposite polarities:
When the platform looks for a credential, it checks the current tenant, then walks up the parent chain until it finds a match or reaches the root. Store an organizational credential at the parent tenant and every child tenant can resolve it automatically — define your integrations once for the whole org.
A child tenant can **shadow** a parent's credential by creating one with the same name; the child's takes precedence within its scope. Names are unique within a tenant, which is what makes name-based shadowing work.
Grants also resolve up the hierarchy, but a child can only **add restrictions** — never exceed the parent. Tenant policies set the outer boundary that neither creator nor invoker grants can exceed. A child agent's grants are a subset of its parent's, enforced at launch.
So inheritance never leaks authority downward. A parent can widen; a child can only tighten.
## A worked example
An organization stores one Google Drive credential scoped to its financial records at the **org (parent) tenant** — call its resource `credential:crd_gdrive_financials`. Because credentials walk up the hierarchy, **every department inherits it**: marketing, engineering, accounting all resolve the same credential.
But only principals in the **accounting** department hold the grant that authorizes *using* it:
```text theme={null}
resource: credential:crd_gdrive_financials
action: use
effect: allow
```
Now launch an agent in the **marketing** department that tries to read those financial records:
Walk-up resolution can find `crd_gdrive_financials` at the parent tenant — every department inherits it, so it is available for the marketing agent to resolve.
Using that credential requires a grant: `credential:crd_gdrive_financials` with action `use`. The engine looks for one on the marketing principal and finds none — that grant lives only on accounting principals.
No matching grant means deny. Inheritance put the credential within reach; without the grant, the marketing agent is refused — whether that refusal lands at launch or at first use, the answer is no.
The moral for both buyers: **possessing or inheriting a credential confers nothing.** Capability stays inert until a grant authorizes its use, and the default is deny. Inheritance spreads *availability*; grants control *permission*; the two never collapse into each other.
## How this shows up
Where credentials and grants sit in the control plane, harness, and agent lifecycle.
The guardrails discipline in a real coding agent — tiered permissions and hard-deny secret guards.
A go-to-market workspace running on platform-governed credentials and grants.