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

# Quick Start

This quick start gives a release pipeline its own service account, a role with exactly the three actions it needs, and nothing else. The [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) sends every IAM request with an API key of the owner.

> [!CAUTION]
>
> Enabling IAM before the roles and grants exist locks out every user and service account without a grant.

## 1. Create a Service Account

The pipeline gets a [service account](https://developers.telnyx.com/docs/iam/principals/service-accounts.md) of its own instead of a person's key.

```json POST /v2/iam/service_accounts theme={null}
{
  "name": "test-number-ci",
  "description": "Orders test numbers from the release pipeline"
}
```

```json Output theme={null}
{
  "data": {
    "id": "e6cd1ff6-6e3a-4ff3-88d5-2234142c1df2",
    "name": "test-number-ci",
    ...
  }
}
```

## 2. Issue Its Token

```json POST /v2/iam/service_accounts/{id}/tokens theme={null}
{
  "name": "release-pipeline"
}
```

```json Output theme={null}
{
  "data": {
    "token": "<shown only in this response>",
    ...
  }
}
```

The pipeline stores `token` and sends it as `Authorization: Bearer <token>`. Telnyx shows the value in this response only.

## 3. Write the Role

The pipeline searches for numbers, orders one, and assigns it to a SIP connection. Those are three [actions](https://developers.telnyx.com/docs/iam/access/actions.md), and the [role](https://developers.telnyx.com/docs/iam/access/roles.md) holds exactly those.

```json POST /v2/iam/roles theme={null}
{
  "name": "test-number-provisioner",
  "description": "Searches, orders and assigns test numbers"
}
```

```json Output theme={null}
{
  "data": {
    "id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
    "name": "test-number-provisioner",
    ...
  }
}
```

```json POST /v2/iam/roles/{role_id}/statements theme={null}
{
  "actions": [
    "phone_numbers.list",
    "number_order.create",
    "number.update"
  ]
}
```

```json Output theme={null}
{
  "data": {
    "effect": "allow",
    "actions": [
      "phone_numbers.list",
      "number_order.create",
      "number.update"
    ],
    ...
  }
}
```

## 4. Grant the Role

A [grant](https://developers.telnyx.com/docs/iam/access/grants.md) gives the role to the service account.

```json POST /v2/iam/grants theme={null}
{
  "role_id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
  "principal_type": "service_account",
  "principal_id": "e6cd1ff6-6e3a-4ff3-88d5-2234142c1df2"
}
```

```json Output theme={null}
{
  "data": {
    "id": "b4c4bb86-5a8f-4414-b011-93592888edf7",
    "record_type": "iam_grant",
    ...
  }
}
```

## 5. Check the Grants

Before turning IAM on, every user and service account that must keep working needs a grant, because a principal without one is refused everything afterwards.

```json GET /v2/iam/grants theme={null}
{
  "data": [
    {
      "principal_type": "service_account",
      "principal_id": "e6cd1ff6-6e3a-4ff3-88d5-2234142c1df2",
      "role_id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
      ...
    }
  ],
  "meta": { "total_results": 1, ... }
}
```

## 6. Enable IAM

```json PATCH /v2/iam/settings theme={null}
{
  "enabled": true
}
```

```json Output theme={null}
{
  "data": {
    "enabled": true,
    ...
  }
}
```

From here on, the roles decide every request from the organization's users and service accounts. The owner is unaffected. See [Enable IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md).

## 7. Verify

With the service account's token, the pipeline searches for numbers.

```http theme={null}
GET /v2/available_phone_numbers?filter[country_code]=US
Authorization: Bearer <service account token>
```

The request needs `phone_numbers.list`, the role allows it, and the numbers come back. The same token then tries to edit the SIP connection itself.

```http theme={null}
PATCH /v2/credential_connections/1850335226672022881
Authorization: Bearer <service account token>
Content-Type: application/json

{"connection_name": "changed"}
```

```json Output theme={null}
{
  "errors": [
    {
      "code": "10010",
      "detail": "no grant allows connection.update",
      ...
    }
  ]
}
```

The pipeline searches, orders, and assigns test numbers. It cannot change connections, outbound voice profiles, billing, or anything else, and the response says which action it lacked. See [Evaluation Sequence](https://developers.telnyx.com/docs/iam/troubleshooting/evaluation-sequence.md).
