Skip to main content
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.
POST /v2/iam/service_accounts
Output
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.
POST /v2/iam/service_accounts/{id}/tokens
Output
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 gives the service account one role, and it can hold up to ten. Their statements decide every request its tokens send.
POST /v2/iam/grants
Once the organization has enabled IAM, 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.

Workloads Outside Telnyx

Preview A service account trusts workloads 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. Preview A token can name the networks it accepts requests from.