# Credential Policies

Credential policies let you define the operating envelope for an identity or key before a token is issued. Instead of making authorization decisions only downstream, you can prevent risky credentials from being minted in the first place.

### What A Policy Controls

A credential policy can constrain:

* maximum token TTL
* allowed grant types
* allowed scopes
* required trust level
* required attestation level
* maximum delegation depth

That means policies are not just metadata. They participate directly in issuance decisions.

### Why Policies Matter

Without issuance policy, an agent might:

* request a longer TTL than you want
* use a grant type you did not intend
* ask for broader scopes than its runtime role should have
* delegate deeper into a chain than your system can reason about safely

Credential policies give you a first control point before the token leaves ZeroID.

### Example Policy

Python:

```python
policy = client.credential_policies.create(
    name="orchestrator-production",
    description="Restrictive policy for first-party orchestrators",
    max_ttl_seconds=900,
    allowed_grant_types=["client_credentials", "token_exchange"],
    allowed_scopes=["data:read", "tickets:write"],
    required_trust_level="first_party",
    max_delegation_depth=1,
)
```

This policy means:

* tokens expire in 15 minutes or less
* only two issuance flows are allowed
* scopes are restricted to a known set
* only first-party identities qualify
* a single delegation hop is permitted

### Choosing Good Defaults

For developer-facing open source adoption, these defaults are usually sane:

* short TTLs for interactive or tool-facing agents
* explicit allowed grant types
* explicit allowed scopes
* low max delegation depth until you have a reason to increase it

For production:

* prefer the smallest useful TTL
* do not allow all grant types by default
* gate sensitive identities behind trust-level or attestation requirements

### Policy Design Patterns

#### Pattern 1: Local Development Policy

Use when developer friction matters more than strict enforcement:

* longer TTL
* fewer trust checks
* narrow but practical scopes

#### Pattern 2: Tool-Agent Policy

Use for narrow execution roles:

* very small scope set
* low TTL
* no further delegation

#### Pattern 3: Orchestrator Policy

Use for agents that coordinate sub-agents:

* moderate TTL
* allow `token_exchange`
* set explicit `max_delegation_depth`

#### Pattern 4: Sensitive Production Policy

Use where agents touch regulated or high-risk systems:

* short TTL
* required trust level
* required attestation
* minimal scope set

### Example REST Call

```bash
curl http://localhost:8899/api/v1/credential-policies \
  -H "Content-Type: application/json" \
  -H "X-Account-ID: acct-demo" \
  -H "X-Project-ID: proj-demo" \
  -d '{
    "name": "tool-agent-default",
    "max_ttl_seconds": 600,
    "allowed_grant_types": ["token_exchange"],
    "allowed_scopes": ["data:read"],
    "required_trust_level": "first_party",
    "max_delegation_depth": 0
  }'
```

### How Enforcement Works

At issuance time, ZeroID checks the request against the assigned policy. If the request violates the policy, issuance is denied before a credential is created.

That makes policies complementary to downstream authorization:

* **policy** decides whether a token may be minted
* **downstream authorization** decides whether the token may perform a specific action

You usually want both.

### Common Mistakes

Avoid:

* allowing every grant type for convenience
* letting orchestrators delegate indefinitely
* using the same policy for orchestrators, tool agents, and background services
* relying on downstream checks alone while leaving issuance wide open

#### What's Next?

* Continue to [**Downstream Authorization**](https://docs.highflame.ai/documentation/agent-identity/guides/downstream-authorization) to enforce what issued tokens can do.
* Revisit [**Token Flows**](https://docs.highflame.ai/documentation/agent-identity/concepts/token-flows) if you are deciding which grant types to permit.