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 are limited in their capabilities by a permissions system which controls what they can and cannot do. An organization owner is fully privileged by default (and can essentially "do anything" with the account), including managing the permissions of the sub-users in the 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.
A non-organization user may start an organization if they are level 1 verified by going to the account → organizations page. Once a user has created an organization, they will be able to send invitations to others to join the organization. They will also be able to see and manage any invitations they have sent that have not been accepted.
Invitations are sent to invite people to join an organization. IMPORTANT: EXISTING USERS GENERALLY CANNOT BE CONVERTED INTO ORGANIZATION SUB-USERS.
A user, that you want to send an invite to join your organization, can't be signed up with Telnyx already otherwise they are classed as an existing user.
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.)
Groups & Permissions
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 in 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 behavior 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.
Limitations on ownership
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.
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 permissions, in this instance to view numbers, you will see this general error display. Please contact your organization owner to discuss which permissions you should have on your sub account.
Without having any permissions assigned, you will still have access to:
- API TOKENS
- ACCOUNT - specifically General, Organizations and Notifications
- DEBUGGING TOOL
You can only create one organization per account.
If you have sent an invite to a member, you can delete the invitation which will disallow them from becoming apart of your organization but only if they have not accepted the invitation.
We recommend that you only send invitations to people you really want to have apart of your organization so you can delegate certain permissions to them via the permission groups you create.
If they have accepted the invitation and signed up but you don't want them to continue to be apart of your organization please do not give them permissions in any permissions group or remove them from any permissions groups which you have included them in already.
The organization owner should then contact email@example.com requesting that a user be blocked if they do not want that user to be apart of their organization anymore, as technically they would still have access to the above 4 points.
You can't remove an individuals email that an invitation has been sent to, the revoked status is when you send an invitation but then delete it afterwards.
They will still receive the email but if they sign up, they will not be apart of your organization. This is as long as you have deleted the invitation, otherwise if they sign up they will be apart of your organization.