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

# Service Accounts

A service account is a principal for a workload. Servers, pipelines, and integrations run as one, and each service account authenticates with its own tokens instead of a person's API key. A service account never holds an API key.

## Creation

A service account belongs to one organization and has a name and a description.

```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",
    "status": "active",
    ...
  }
}
```

`GET /v2/iam/service_accounts` lists the organization's service accounts, `PATCH /v2/iam/service_accounts/{id}` renames one, and `POST /v2/iam/service_accounts/{id}/actions/disable` stops every token it holds until `.../actions/enable`.

## Tokens

A service account token authenticates a request as the service account. Telnyx returns its value in the creation response only.

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

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

The workload sends the token as `Authorization: Bearer <token>`. `DELETE /v2/iam/service_accounts/{id}/tokens/{token_id}` revokes it, and `.../tokens/{token_id}/actions/deactivate` pauses it.

## Grants

Each [grant](https://developers.telnyx.com/docs/iam/access/grants.md) gives the service account one [role](https://developers.telnyx.com/docs/iam/access/roles.md), and it can hold up to ten. Their statements decide every request its tokens send.

```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"
}
```

Once the organization has [enabled IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md), the grants decide, and the `action_ids` and `role_ids` a service account carries from before IAM no longer apply. A service account without a grant is refused every action.

A service account token cannot manage IAM. Roles, grants, and settings are changed by the [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md).

## Workloads Outside Telnyx

Preview A service account [trusts workloads](https://developers.telnyx.com/docs/iam/principals/trusted-workloads.md) such as a GitHub Actions job, which then trades its own token for a short-lived Telnyx token instead of storing one.

## One Service Account per Job

A service account token carries no scope. Every token of a service account does exactly what its roles allow, so a job that needs fewer actions gets a service account of its own with a narrower role. Scopes exist only on a user's [API key](https://developers.telnyx.com/docs/iam/credentials/scoped-keys.md).

Preview A token can name the networks it accepts requests from.
