> ## 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.

# Scoped Keys

A scoped key is a [user's](https://developers.telnyx.com/docs/iam/principals/users.md) API key that carries statements narrowing what it may do. The user still needs a role that allows the action, and the scope narrows that, never augments it.

Only a user's API key takes a scope. A [service account token](https://developers.telnyx.com/docs/iam/principals/service-accounts.md#tokens) does exactly what the service account's roles allow, so a job that needs less gets a service account of its own with a narrower role.

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

## Scope

A scope is a list of [statements](https://developers.telnyx.com/docs/iam/access/statements.md), set when the key is issued. A key with no scope may do everything its user may do.

```json POST /v2/iam/api_keys theme={null}
{
  "expires_in_days": 90,
  "scope": [
    {
      "effect": "allow",
      "actions": [
        "phone_numbers.list",
        "number_order.create",
        "number.update"
      ]
    }
  ]
}
```

A request with this key needs an allow from the user's [grants](https://developers.telnyx.com/docs/iam/access/grants.md) and an allow from the scope. The scope never augments the grants. Had it listed `connection.*`, the key still could not touch connections unless a granted role allowed them. A read-only user who scopes a key to every action gets a read-only key.

## Networks

A key also names the networks it accepts requests from. A request from any other address answers `401`.

```json POST /v2/iam/api_keys theme={null}
{
  "allowed_ips": ["198.51.100.0/24"],
  ...
}
```

A service account token names its networks the same way, when it is issued at `/v2/iam/service_accounts/{id}/tokens`.

## Key Rules

The organization's [guardrail](https://developers.telnyx.com/docs/iam/access/guardrails.md) can require a scope on every API key and cap how long an API key or a service account token lives, through `require_scope` and `max_lifetime_days` in `/v2/iam/settings`.

## Keys Without a Scope

`/v2/api_keys` keeps working. A key issued there has no scope and does whatever its [user](https://developers.telnyx.com/docs/iam/principals/users.md) may do.
