Skip to main content
This workflow gets you:
  • Every user, API key, and integration keeps working while the roles are written, until the owner enables IAM.
  • Each user holds roles with the actions their job needs.
  • Each integration runs as a service account with its own token, so it no longer depends on a person.
  • After the switch, a request the roles do not cover names the action it needed, and adding that action to a role lets it through within five seconds.
  • Existing permissions carry over as roles, checked against real requests before the switch.Preview
  • Grants name the identity provider’s groups, and production sits in a project of its own.Preview
  • Roles become the only permissions, and permission groups retire.Preview
The org moves to IAM at its own pace. 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.

Day One

Nothing an existing integration relies on changes on the day IAM is made available.
  • The owner keeps every permission.
  • Every user keeps the permissions managed in Mission Control Portal, and every API key keeps doing whatever its user may do.
  • Every service account keeps the actions and roles set on it.
  • Managed organizations keep working as before.
  • Every product credential, such as SIP credentials and Cloud Storage keys, is untouched. IAM governs requests to the Telnyx API only.
Roles and grants can be written while IAM is off, with no effect on live requests.

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

2. Hand IAM to the Admins

Preview The owner grants the ready-made Org Admin role to the platform team, and stops being the only one who can change access.

3. Give Every User a Role

The owner writes a role for each job from the actions behind the requests that job sends. The catalog finds the action behind a route.
GET /v2/iam/actions?filter[path][contains]=messaging_profiles
A user who runs both voice and messaging holds two roles, one grant each, and their statements add up. Every user and service account that sends requests needs a grant before IAM is enabled, including the integrations that run on a person’s API key. Permission groups in Mission Control Portal keep applying to users on top of their roles, so a user needs both until the groups retire. Preview Telnyx carries existing permissions over as roles. A user with no permissions set gets the visible role Legacy full access, and a user’s existing permission set becomes a role with the same actions. The owner replays a user’s requests from the last month against the new roles with simulate before revoking Legacy full access.

4. Move an Integration Off a Person’s API Key

An integration that runs on a person’s API key, such as a server that reads balances and invoices, moves to a service account of its own, so it no longer depends on that person.
POST /v2/iam/service_accounts
POST /v2/iam/roles/{role_id}/statements
The owner grants that role to the service account, issues it a token, and deploys the token to the server. Once the integration runs on the new token, the person’s key is revoked. Preview The credential inventory shows which actions each key sent in the last 30 days, and from which addresses, so the right role is clear before the move. See Audit Events.

5. Enable IAM

PATCH /v2/iam/settings
Every user and service account is then decided by its roles. A request the roles do not cover answers 403 with the action it needed, and adding that action to a role lets it through within five seconds. See Denied Requests.

6. Create Projects and Move Production In

Preview The organization creates prod and moves its production numbers, connections, and messaging profiles into it, so grants can say prod or staging. The step is optional, and nothing else in the migration depends on it. See Projects.

7. Narrow the Managed-Organization Delegations

Preview In each managed organization, the support team gets Read-only and the platform team keeps Org Admin, instead of everyone in the organization holding Org Admin. Every change in the managed organization then names the user who made it. See Delegations.

8. Apply the Enterprise Template

Preview The organization applies the enterprise template last, because its guardrail stops API keys working at all. Every integration runs on a service account by then.

Retiring Permission Groups

Preview Permission groups in Mission Control Portal, policies, and the action lists on service accounts retire with notice, once every organization has its roles. Roles are then the only permissions.