> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardrails

A guardrail is a list of statements on the whole organization. Every request in the organization must pass it, the owner's included, so it is where an organization writes the rules nobody may break.

> [!WARNING]
>
> **Preview.** Not available yet.

## The Organization's Guardrail

Each organization has exactly one guardrail. It starts from `allow *` and takes away, so an organization with no guardrail adds no limit.

```json PUT /v2/iam/guardrail theme={null}
[
  { "effect": "allow", "actions": ["*"] },
  {
    "effect": "deny",
    "actions": ["api_keys.create"]
  },
  {
    "effect": "deny",
    "actions": ["number.delete"],
    "projects": ["prod"]
  }
]
```

This guardrail stops anyone, the owner included, from creating an API key or releasing a production number. API keys belong to users, so automation keeps running on service account tokens.

Changing the guardrail is an action, `iam.guardrail.update`, granted like any other.

## Retiring API Keys

One line retires every API key still in use without touching anything else.

```json theme={null}
{
  "effect": "deny",
  "actions": ["*"],
  "conditions": {
    "auth_method": ["api_key"]
  }
}
```

A person signed in with a session or through OAuth is unaffected, and so is a service account using its token.

## Up to Three Guardrails

A request must pass every guardrail that applies to it.

* The organization's own.
* The one its manager organization sets, if it is a [managed organization](https://developers.telnyx.com/docs/iam/access/delegations.md). It binds everyone working there, manager org users included, and only the manager org can change it.
* The requester's home organization's, when someone works in another organization through a delegation.

A manager sets a guardrail on one managed organization at `/v2/iam/delegations/{id}/guardrail`, or on all of them at `/v2/iam/delegation_defaults/guardrail`.

## Key and Token Rules

A guardrail allows or denies actions and never inspects what a request sets. The one exception is IAM's own key and token rules in `/v2/iam/settings`.

```json theme={null}
{
  "keys": { "require_scope": true, "max_lifetime_days": 90 },
  "service_account_tokens": { "max_lifetime_days": 90 }
}
```

Every new API key then needs a [scope](https://developers.telnyx.com/docs/iam/credentials/scoped-keys.md), and every new API key or service account token lives at most ninety days.
