Telnyx User Management API Guide

Auth method: API Key (Bearer token) - passed as Authorization: Bearer header. No OAuth 2.0 documented.

Setup steps

1. Log in to the Telnyx Mission Control Portal (portal.telnyx.com).
2. Navigate to Auth > API Keys.
3. Click 'Create API Key', optionally name it, and copy the generated key.
4. Pass the key in all API requests as the Authorization header: 'Authorization: Bearer '.

List sub-users

• Method: GET
• URL: https://api.telnyx.com/v2/sub_users
• Watch out for: Returns only sub-users under the authenticated account's organization; does not return the root account owner.

Request example

GET /v2/sub_users?page[size]=20 HTTP/1.1
Authorization: Bearer <API_KEY>

Response example

{
  "data": [
    {"id":"uuid","email":"user@example.com","name":"Jane Doe","role":"member","status":"active"}
  ],
  "meta": {"total_results": 1, "page_number": 1}
}

Get sub-user

• Method: GET
• URL: https://api.telnyx.com/v2/sub_users/{id}
• Watch out for: Returns 404 if the sub-user ID does not belong to the authenticated account.

Request example

GET /v2/sub_users/uuid-here HTTP/1.1
Authorization: Bearer <API_KEY>

Response example

{
  "data": {
    "id": "uuid-here",
    "email": "user@example.com",
    "name": "Jane Doe",
    "role": "member",
    "status": "active",
    "record_type": "sub_user"
  }
}

Create (invite) sub-user

• Method: POST
• URL: https://api.telnyx.com/v2/sub_users
• Watch out for: Creates the user in 'invited' status; the user must accept the email invitation before the account is active. Duplicate email returns 422.

Request example

POST /v2/sub_users HTTP/1.1
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"email":"newuser@example.com","name":"John Smith","role":"member"}

Response example

{
  "data": {
    "id": "new-uuid",
    "email": "newuser@example.com",
    "status": "invited",
    "record_type": "sub_user"
  }
}

Update sub-user

• Method: PATCH
• URL: https://api.telnyx.com/v2/sub_users/{id}
• Watch out for: Only mutable fields (name, role) can be updated. Email changes are not supported via PATCH.

Request example

PATCH /v2/sub_users/uuid-here HTTP/1.1
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"role":"admin"}

Response example

{
  "data": {
    "id": "uuid-here",
    "role": "admin",
    "record_type": "sub_user"
  }
}

Delete sub-user

• Method: DELETE
• URL: https://api.telnyx.com/v2/sub_users/{id}
• Watch out for: Deletion is immediate and irreversible. The sub-user loses all portal access instantly.

Request example

DELETE /v2/sub_users/uuid-here HTTP/1.1
Authorization: Bearer <API_KEY>

Response example

HTTP/1.1 204 No Content

• Rate limits: Telnyx does not publicly document specific rate-limit tiers or per-plan request quotas in their developer docs as of the research date.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No explicit rate-limit values, headers, or Retry-After behavior documented in official sources. Contact Telnyx support for enterprise limits.

• Pagination method: cursor

• Default page size: 20

• Max page size: 250

• Pagination pointer: page[number] / page[size] (JSON:API-style pagination); meta.next_page_url provided in responses

• Webhooks available: Yes

• Webhook notes: Telnyx supports webhooks for communication events (calls, SMS, fax, etc.) configured via the Mission Control Portal or API. There are no documented user-lifecycle webhooks (e.g., user.created, user.deleted) for sub-user management events.

• Alternative event strategy: Poll GET /v2/sub_users periodically to detect user changes, as no user-lifecycle webhook events are documented.

• Webhook events: call.initiated, call.answered, call.hangup, message.received, message.sent, fax.received

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• SCIM provisioning is not documented in Telnyx's official developer or support documentation.
• SAML SSO with Azure AD (Entra ID) is supported but does not include SCIM-based user provisioning/deprovisioning.
• Enterprise plan may include SSO; SCIM availability is unconfirmed - contact Telnyx sales.

For onboarding, POST /v2/sub_users with email, name, and role;

the user is created in 'invited' status and cannot authenticate until the invitation email is accepted - there is no API endpoint to resend that email, only the portal UI.

For deprovisioning, resolve the sub-user UUID via GET /v2/sub_users filtered by email, then DELETE /v2/sub_users/{id};

deletion is immediate, irreversible, and has no soft-delete or suspend equivalent.

For access audits, paginate GET /v2/sub_users?page[size]=250 and extract id, email, role, and status fields - note that the root account Owner is excluded from sub-user listings entirely and must be audited separately.

To build an identity graph across your stack, join the sub-user roster keyed on email against your IdP directory and HR system to surface orphaned accounts;

no last-login timestamp is returned in the sub-user object, so recency signals must come from an external source.

Onboard a new team member

1. POST /v2/sub_users with email, name, and role to create the invitation.
2. Telnyx sends an invitation email to the specified address automatically.
3. User accepts the invitation and sets their password via the email link.
4. Poll GET /v2/sub_users/{id} to confirm status transitions from 'invited' to 'active'.

Watch out for: The sub-user cannot log in or use the portal until the invitation is accepted. There is no API endpoint to resend the invitation email - this must be done via the Mission Control Portal UI.

Deprovision a departing employee

1. GET /v2/sub_users to retrieve the sub-user's UUID by matching on email.
2. DELETE /v2/sub_users/{id} to immediately revoke portal access.
3. Verify deletion with GET /v2/sub_users/{id} - expect 404 response.

Watch out for: Deletion is irreversible. There is no suspend/deactivate endpoint; the only option is full deletion. Any API keys the sub-user created under their own profile should also be revoked separately.

Audit all sub-users and their roles

1. GET /v2/sub_users?page[size]=250 to retrieve the first page of sub-users.
2. Check meta.total_results and iterate through pages using page[number] until all records are retrieved.
3. Extract id, email, name, role, and status fields for each record.
4. Compare against your HR system or IdP directory to identify orphaned accounts.

Watch out for: The API does not return the root account owner in sub-user listings. Ensure your audit process accounts for the primary account separately. No last-login timestamp is returned in the sub-user object.

The most consequential caveat is that SCIM is not available - SAML SSO with Azure AD is supported, but it provides authentication only, not provisioning or deprovisioning. Any integration built on the assumption that IdP group changes will propagate to Telnyx will fail silently; deprovisioning must be triggered explicitly via DELETE.

A second trap: API keys are account-scoped with no granular permission model, so a leaked key exposes the full sub-user management surface alongside all other v2 endpoints - key rotation hygiene is critical. Finally, the 'invited' status gap means programmatic onboarding flows cannot be fully automated end-to-end;

a human action (email acceptance) is always required before a new sub-user becomes active.