Zoom Developer Platform — Account Paradigm
We have recently launched our developer platform (https://zoom.us/developer) with a comprehensive list of APIs and cross platform native SDKs. Over the last few months, we have received tons of questions on the account structures and plans in relation to our APIs. This is an attempt to provide more clarification than what is available in our documentation (which will be revised soon).
Every Zoom account is identified through an account id that is generated when the account is created. There are two types of accounts that can be created in Zoom platform:
Master Account — A master account is setup by Zoom on-boarding team. This cannot be created by any other means. A master account is created with a default user who is designated as the account admin or account owner. The admin privilege lets the admin completely control all aspects of that account.
Sub-account — A sub-account has a direct relationship to master and can be created either by the master account admin or through REST API. Again, a default user gets created who will be the admin of the sub-account. As with master account, a sub-account is identified with an account id.
Users — A user account can be created by the account admin associated to master or sub. A user account is created in the context of master or sub — it always belongs to either one of them.
In summary, internally, all accounts are user accounts with a flag in schema that indicates if it’s a master or sub account and whether the logged in user is an admin of that account.
A distributor might have multiple resellers in turn will have subscribers and end users. The relationship model is:
Only 2 levels are allowed (master->master->sub OR master ->sub) from the distributor master account. The distributor master can have subs or masters and each master can have a sub.
These relationship models do not change the fundamental concepts of master/sub/user accounts. Distributors and Resellers gets discounts off of zoom list price. That’s all.
A distributor account needs to be manually setup by Zoom and cannot be auto managed through APIs.
Differences between Master and Sub
· A master account needs to be provisioned by Zoom while sub accounts can be created through REST APIs
· At the time of creating the account, the admin must specify who (master or sub account holder) pays for that account
· A sub account cannot have another down level hierarchy
· A sub account can be deleted by master and a master account can only be deleted by Zoom
· The users created on the master account cannot be free users (unlike sub where all users can be basic users)
· All other operations on master and sub accounts are the same
Licenses, Plans and Accounts
· Except for the API per minute plan, all Zoom plans are license based. At the time of creating users, the admin (or through API), needs to specify the user type. If the user type is basic, then that user is a “free” user and no license is assigned. If the user type is not basic, then then a pro license is assigned by the platform (provided, the account admin has subscribed to a plan)
· At the time of creating sub accounts, the admin needs to specify the type of plan that is going to be subscribed
· Note that a plan is different from a license. A plan is associated with an account and a license is associated to a user
· The API per minute plan is a usage based plan. It just means that the account admin can create any number of users through the API, those users can host meetings or webinars and will be billed on the aggregated usage — if a user hosts a 10 minutes meeting with 5 attendees, the total minutes would be 50
· Master and sub can be on different plans and different subs within a master can be on different plans
Account management through APIs
REST APIs are secured through an API key pair that the master admin can get after logging into the master account and selecting zoom developer portal. The API key pair identifies the account and needs to be properly secured. Each account has an unique API key pair.
All sub-account management APIs starts with the URL https://api.zoom.us/v1/ma/account/
To create a sub-account and add a plan to it:
https://api.zoom.us/v1/ma/account/create — create an account and owner
https://api.zoom.us/v1/ma/account/plan/subscribe — subscribe a plan for the sub account
Account APIs are not available in the API playground for security reasons.
Vanity URLs (such as abc.zoom.us) can be configured for master accounts or sub accounts and allows direct access to the account. Vanity URL is just a canonical name in the DNS entry which points to an account. Vanity URL request needs to be submitted by the account admin by logging into the account. Once Zoom operations receives the request, a CNAME entry will be added to Zoom DNS service and the account admin will be notified. This is a manual process and there is no API support at this point to automate this.
Note that each user within an account can get a personal meeting room URL — the format of that would be “subdomain.zoom.us/my/name” — the name can be customized by the user in the account profile.
CRUD operations on the user accounts can be done through the user management API’s - https://api.zoom.us/v1/user/*.
· User management API (https://api.zoom.us/v1/user/create) allow user creation with validation e-mails where the new user will get an e-mail notification and validate the account
· Another option is to use autocreate API (https://api.zoom.us/v1/user/autocreate) - users created with this option will not get validation e-mails but they should belong to the same managed domain as that of the account. For example, if the account managed domain is set to “abc.com”, the user e-mail accounts should belong to the same domain – otherwise, the call will fail with a 4xx response
· A third option is to use autocreate2 API ((https://api.zoom.us/v1/user/autocreate2) - users created with this option will not get validation e-mails and also need not belong to the same domain. However, due to security risk, Zoom partners should explicit request to enable this API on their account
· A fourth option is to use custcreate API (https://api.zoom.us/v1/user/custcreate) - you can use this API if your account is set to use API per minute usage – all users created with this option will not get validation e-mails but they will not be able to login into zoom.us user portal. The expectation here is that the partners will manage the users on their web portal
Examples of creating accounts and users
Reseller ABC signs a reseller agreement with Zoom. ABC has signed up 2 customers — GOOG and FB. ABC wants to manage this through the APIs. ABC is not planning to create users in the master account and will create another sub-account for its internal use if there is a need.
Implementation and Steps
1. Zoom onboarding team creates ABC master account with an admin user and provides the documentation to ABC
2. ABC now login to zoom.us and get api key pair to use Zoom API. ABC calls https://api.zoom.us/v1/ma/account/create to create the sub and admin user accounts for GOOG and FB. This API also lets ABC to specify who pays for the account (master or sub itself), billing (send invoice or bill online) etc.
3. ABC needs to call https://api.zoom.us/v1/ma/account/plan/subscribe and subscribe to the plans for the account
4. In order to add users to the sub-account, ABC needs to get hold of sub API key pair. ABC can call zoom support to enable accessing this API key pair for the sub account. Once this is enabled by Zoom support, ABC can call https://api.zoom.us/v1/ma/account/get to get the sub account api key pair
5. ABC can now use sub API key pair of GOOG and FB to start creating/managing users, add additional plans, get meeting meta-data, recordings etc.