# 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**](/agent-identity-zeroid/guides/downstream-authorization.md) to enforce what issued tokens can do.
* Revisit [**Token Flows**](/agent-identity-zeroid/concepts/token-flows.md) if you are deciding which grant types to permit.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/agent-identity-zeroid/guides/credential-policies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.