# Credential mental model

> Understand Credentials, CredentialProviders, Resources, bindings, AuthProviders, and their security boundaries.

The credential system has distinct objects because external authority has a different lifecycle from code, configuration, identity, and policy. Keeping those responsibilities separate prevents a user request from selecting a secret and lets one agent safely serve many owners.

## Credential {#credential}

A Credential is a stable Resource identity with encrypted versions. Consumers bind the Credential CRN, not a version. Rotation can activate a new version without changing the consuming Resource or the agent's logical dependency.

The Credential document contains metadata, fingerprints, lifecycle state, provider identity, and non-secret configuration. It never contains secret material.

## CredentialProvider {#credential-provider}

A CredentialProvider defines how material is acquired and maintained. It may:

- import material supplied by an operator;
- mint material without a browser;
- begin and complete interactive authorization;
- verify, rotate, refresh, or destroy material.

An installed provider is a configured tenant Resource. A provider package is immutable reusable code from the catalog. These are different objects: the package defines behavior; the installed provider binds configuration and bootstrap Credentials.

## Resource and Driver {#resource-and-driver}

Agents should normally invoke a Resource rather than read a Credential directly. The Resource's Driver owns the operation contract and interprets its named Credential slots. For example, a GitHub Resource can expose repository operations while its Driver injects an installation or user token.

## Scoped binding {#scoped-binding}

A scoped binding is a server-side assignment:

```text
(target class, logical key, authenticated owner) → exact target CRN and hash
```

The authored selector chooses `tenant`, `customer`, or `principal` ownership. The authenticated request supplies the exact owner. Agent input cannot supply a target CRN. Missing narrower assignments never fall back to broader scopes.

## AuthProvider is different {#auth-provider}

An AuthProvider authenticates incoming Channel evidence and produces a subject, bounded claims, optional external customer identity, and expiry. It does not create outbound Credentials and cannot grant tenant, role, scope, or Policy authority.

A CredentialProvider creates outbound authority for Resources. Signing in to call an agent must not silently grant that agent access to act on the caller's external account. If both are desired, require explicit consent and create a principal-scoped Credential separately.

## Resolution sequence {#resolution-sequence}

1. The Channel AuthProvider authenticates the caller.
2. Central Policy authorizes Channel and Agent invocation.
3. Constal derives the tenant, optional customer, and principal.
4. Scoped selectors resolve Resources and their Credential slots.
5. `binding:use`, Resource, and `credential:use` Policies are evaluated.
6. Exact targets, hashes, binding revisions, contracts, and Policy decisions are pinned into the accepted run.

This ordering is what makes a shared agent safe: identity selects authority; untrusted input does not.