Skip to main content
This workflow gets you:
  • Each user holds the actions their job needs, and nothing else.
  • A deny statement keeps a destructive action, such as deleting a SIP connection, out of reach of everyone on a team.
  • Each pipeline runs as a service account with its own token, never on a person’s API key.
  • A refused request names the action it needed.
  • Grants name the identity provider’s groups, and the identity provider adds and removes users.Preview
  • CI deploys with no stored Telnyx credential, and each service account token is limited to its network.Preview
  • Projects keep production apart from staging.Preview
The steps build on each other in order. A step marked Preview can be skipped, and every other step still works.
Enabling IAM before the roles and grants exist locks out every user and service account without a grant.

1. Sign Up

The user who signs up and creates the organization is its owner. The owner holds every action, manages IAM, and is never limited by it. Preview The owner grants the ready-made Owner role to a second user, so the organization has a second owner for recovery.

2. Connect an Identity Provider

Single sign-on is optional, and IAM works the same without it. An organization that wants it connects its identity provider in Mission Control Portal. Preview Its groups then become principals that grants can name. See Identity Provider.

3. Apply the Enterprise Template

Preview One request turns API keys off and limits every service account token to 90 days. See Enterprise Template.

4. Hand IAM to the Admins

Preview The owner grants the ready-made Org Admin role to the platform team, which runs IAM from there.

5. Create Projects

Preview The organization creates prod and staging, builds new resources into them, and adds a guardrail that stops anyone, the owners included, from releasing a production number. Projects are optional, and every later step works the same without them. See Projects.

6. Give a User the Actions for the Job

A user who buys and ports numbers needs number orders and port requests, and nothing else. The owner writes a role from the actions behind those routes.
POST /v2/iam/roles
POST /v2/iam/roles/{role_id}/statements
A grant gives the role to the user.
POST /v2/iam/grants

7. Write Roles for the Teams

A team that runs SIP connections and outbound voice profiles, and assigns numbers to trunks, gets one role. An allow statement covers the work, and a deny statement keeps anyone on the team from deleting a connection.
POST /v2/iam/roles/{role_id}/statements
POST /v2/iam/roles/{role_id}/statements
The owner grants the role to each user on the team. Preview A grant names the team’s identity-provider group instead of each user, so joining or leaving the group changes access with it.

8. Give Each Pipeline a Service Account

A CI pipeline that searches for numbers, orders one, and assigns it to a SIP connection gets a service account of its own, with a role that holds exactly phone_numbers.list, number_order.create, and number.update. The Quick Start walks through these requests.

9. Enable IAM

Every user and service account that must keep working holds a grant before the switch, because a principal without one is refused everything afterwards.
PATCH /v2/iam/settings
The user from step 6 then tries to point a number at a SIP connection, which needs number.update.
Output
The user orders and ports numbers and nothing else. See Enable IAM.

10. Deploy From CI Without a Stored Credential

Preview A deploy job in a CI system such as GitHub Actions runs as a service account that trusts it. Each run trades the CI system’s token for a one-hour Telnyx token, so no Telnyx credential is stored in the CI system. See Trusted Workloads.

11. Accept the CI Token Only From the Build Network

Preview The pipeline’s service account token accepts requests only from the build network’s addresses. A request from anywhere else gets 401. See Service Accounts.

12. Let the Identity Provider Add and Remove Users

Preview With SCIM on, the identity provider creates and removes Telnyx users and keeps group membership in step. A user removed there loses Telnyx access at once. See Identity Provider.

13. Find Out Why a Request Was Refused

A refused request names the action it needed and the roles that denied it. See Denied Requests. Explain answers the same question before the request is sent, and simulate checks a role change against a list of requests first. See Explain and Simulate.