What are User Organizations?

User organizations, also frequently just referred to as "organizations," is a feature that allows multiple user accounts to be tied together into one larger "umbrella" entity. An organization is always headed by a single account, the organization owner.

Sub-accounts, also known as sub-members or sub-users, are limited in their capabilities by a permissions system that controls what resources they can and cannot access on your account. An organization owner is fully privileged by default (and can essentially "do anything" with the account), including managing the permissions of the users in their organization.
​
The permissions are managed on a group-level, rather than an individual level, to ensure that it is easy to assign the same permissions to any number of sub-accounts as needed.

In all cases, user organizations are allowed only one net running balance and payment method - it is not meant to be a system for re-sellers to allow their customers access to their Telnyx account directly. Please check out our managed accounts feature instead.

The Organizations section is located under "Account Settings" and "Advanced Features" in the sidebar of the Mission Control Portal.

A non-organisation user may start an organisation once they are level 1 verified.

Once a user has created an organisation, they will be able to send email invitations to others to join the organisation as sub members.

They will also be able to see and manage any invitations they have sent that have not been accepted.

How can I add users to my account?

Invitations are sent to invite people to join an organization. A user, that you want to send an invite to join your organization, must not be signed up with Telnyx already in order for them to be invited. Once the user accepts, they become a sub-member of your organisation.

Invitations can be revoked once sent to prevent using them to sign up to join the organization. (Note that revoking an invitation does not prevent the person from signing up for Telnyx entirely, but if they do sign up, they will be a separate non-organization account like normal.)

Please note there are limits surrounding invites to an organization.

Once a sub member has accepted an invitation, you can then proceed to creating a permission group in which they can be added to. In this permission group, you define the permissions the user is allowed.
​
For example, the below permission group is called "billing permissions" and I have one member assigned to it. I will provide this member with billing permissions, so they can assist with payments, downloading invoices, pricing etc.

As an organization owner, you can delegate the exact permission set required to your sub member based on the tasks they can help complete on your behalf. The ideal case is that you create a permission group that's named after the permissions you want to make available.

These available permission sets, with a brief description of what they allow you to do, are shown below. The pictures include an example of what permissions are enabled with the green filled backgrounds.

Manage general account preferences such as balance, pricing, auto-recharge, payment method, adding funds, and invoices.

Create, read, update and delete connections or applications.

Manage Bulk Number Updates, Channel Settings, Number (DID) Settings, Number Deletions, Number Purchasing and Telephone Data Integration settings.

Manage Bulk Number Updates, Channel Settings, Number (DID) Settings, Number Deletions, Number Purchasing and Telephone Data Integration settings.

Manage outbound profile settings by toggling Modify, Read-only and None options.

Enable access to generate Detail Requests, Usage Reports, and Monthly charge reports.

Create new port requests, manage existing requests, and manage port out requests.

Allow the ability to create managed accounts and impersonate them (login as).

Manage Virtual Cross Connect Requests by providing permission to create, read or delete.

Managing messaging settings for a number through create, read, update and deleting messaging profiles.

Manage users in the organization. This allows inviting new users to the organization, cancelling invitations to the organization, and cancelling active accounts in the organizations.

Manage organization groups, group membership and permissions given to groups. This permission should be considered an admin-level permission, as it will allow them to grant any user, including themselves, any number of permissions.

Managing sim card order, registering and decommissioning sim cards. Manage the changes and visibility of SIM cards including bulk actions. Manage private wireless gateways.

Manage Access Control Resources giving them the ability to create, read, update and delete any ACL entries.

Manage call recording settings giving them the ability to create, read, update and delete call recordings.

In my example, I have provided my sub member with the following permissions.

The sub member, when logged in, will be able to view the accounts balance, pricing information, modify auto recharge preferences for payments, modify payment methods, add any funds and view start of month invoices for generated from the previous month.

A sub-account cannot "own" most things in the system, such as numbers, connections, outbound profiles, etc. Instead sub-accounts interact with things owned by the organization owner, which is exposed to these sub-users via the organization permission system.

A sub-account cannot have it's own payment information either, it instead performs all payments (if granted the permission to do so) on behalf of the organization owner.

When your sub account does not have the appropriate access or permissions, in this instance to view numbers, you will see this general error display.

Whilst we try to cover and provide as many permission sets to as many features as possible, sub members have access to the following sections but may see undesired results. This is due to our migration to V2, in which not all our new V2 services are exposed to the organizations functionality. In time, this behaviour will change and sub members will be provided with the relevant permissions but for now, we strongly recommend that sub members leverage the API key of their organization owners account.

Sub members do not have access to the verification or single sign on pages as these can only ever required/configurable by the organisation owner. If a sub member attempts to paste the url of these links into the webpage, they will be met with an error.

The way in which sub-users are given the ability to do things on behalf of an organization is through a granted permission, and permissions are always granted to groups. A single user can be in any number of groups, and will always have the net MOST PERMISSIONS possible based on all of the groups they are in.

Permissions come in two types: "category" and "entity" permissions. A category permission is a permission that grants access to a "whole category" of things. For example, a category permission for connections would give members of a group a set of permissions for all connections that belong to the organization. An entity permission is a permission that grants access to "just one" of something.

Please note that in the initial release of User Organizations ONLY category permissions will be present. Entity permissions will be added later in a subsequent release.

Permissions specify how something can be interacted with. The different permissions are:

create permission: the ability to add more of something

read permission: the ability to view something

update permission: the ability to change something

delete permission: the ability to remove/delete something

It is possible to grant permissions to modify something without giving the ability to read it. This will likely result in unintuitive behaviour for portal-using accounts, but it may make sense and be useful for direct API users.

As stated above, a user always has the most permissions possible based on all of the groups they are in. As an example, if a user is in a group that has category read permission for numbers, and in a group that has category update permission for numbers, they will have permission to both read and update all numbers for the organization.

If you have existing numbers on your account that you want to transfer to another account instead, we recommend you submit a port in request for these numbers on the new account.

As for configurations, this is not possible. Once you have the port in requests setup on the new account, and prior to their activation, it's recommended that you set a maintenance outside of business hours to transfer (i.e recreate the configurations associated with the numbers) to the new account, in order to minimise downtime for yourself and your clients.

Note that if you have a SIP Connection on Account X and want to transfer it to Account Y, SIP Connections need to be unique in nature, so you will either need to setup expert authentication methods on the new SIP Connection on Account Y (so it's considered unique in our system) or remove the SIP Connection from Account X in order to be able to recreate it on Account Y.

Unfortunately you are unable to invite a member who already has an existing Telnyx account. The member would need to reach out to support@telnyx.com and request that their account be cancelled and email freed up so you, as the organisation owner, can add them into your organisation.

​