--- title: "Creating and Registering an Enterprise with Restricted Access" slug: "creating-enterprise-with-restricted-access" updated: 2026-04-02T16:26:34Z published: 2026-04-02T16:26:34Z canonical: "kb.connecttoteams.com/creating-enterprise-with-restricted-access" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.connecttoteams.com/llms.txt > Use this file to discover all available pages before exploring further. # Creating and Registering an Enterprise with Restricted Access ## Part I: Creating an Enterprise with Restricted Access ### 1. Retrieve the SBC Gateways If you're creating an enterprise that will use **calling services** (such as **PBX** or **Trunk**), you must first retrieve the list of available SBC (Session Border Controller) gateways. You’ll need the `sbcGatewayId` values to assign appropriate gateways to the enterprise. **API Endpoint** - **Method**: `GET` - **Path**: `/reseller/getAvailableSBCGatewayRegionsByResellerId/{resellerId}` - **Authentication**: [Reseller-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-resellerlevel-bearer-token) **Sample API response** ```json [  {    "sbcGatewayId": 5678,    "sbcGatewayRegion": "US-East"  } ] ``` **Note**: Record the `sbcGatewayId` values of the gateways you plan to assign to the enterprise. ### 2. Retrieve the PBX Types In addition, if the enterprise will be using **PBX** service and/or **CallApp** add-on, retrieve the PBX types available. Take note of the `id` of the PBX Types to assign to this enterprise. **API Endpoint** - **Method**: `GET` - **Path**: `/pbx/getPBXTypesByResellerId?resellerId=<resellerId>` - **Authentication**: [Reseller-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-resellerlevel-bearer-token) **Sample API Response** ```json [  {    "id": 1234,    "pbxName": "Example PBX",    "pbxLabel": "Example PBX Label",    "isDefault": true,    "isDisabled": false,    "hostingType": "Cloud"  } ] ``` **Note**: Record the `id` values of the PBX type(s) you plan to assign to the enterprise. ### 3. Create the Enterprise To create a new enterprise, use the following API endpoint. This step registers the enterprise within the system and assigns PBX types, SBC gateways, and service configurations. **API Endpoint** - **Method**: `POST` - **Path**: `/reseller/newEnterprise` - **Authentication**: [Reseller-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-resellerlevel-bearer-token) **Sample API Request Body** Below is the JSON request body for creating a new enterprise. Required fields are highlighted and explained in detail. ```json {  "allowExternalNumbers": true,  "billingReferences": [    "string"  ],  "canAddExtensions": true,  "canResellerManageEnterpriseProvisioning": true,  "countryName": "string",  "entConfigInfos": [    {      "configDetails": {        "contexts": "string",        "defValue": "string",        "ent": true,        "id": 0,        "labelName": "string",        "labelPopover": "string",        "masterReseller": true,        "name": "string",        "partner": true,        "reseller": true,        "system": true,        "type": "string"      },      "entityId": 0,      "id": 0,      "value": "string"    }  ],  "enterpriseId": 0,  "enterpriseName": "string",    "federated": true,  "federationDomain": "string",  "pbxId": [0],    "pbxMOH": true,  "registeredBy": "string",  "resellerId": 0,  "restrictAdminAccess": true,  "sbcGateways": [0],    "secureSMSEnabled": true,  "services": ["string"],    "userLimit": 0,  "userProvisioningEnabled": true } ``` **Required Fields** - `enterpriseName (String)` - The name of the enterprise to be created. This field is mandatory as it uniquely identifies the enterprise in the system. - `pbxId (Array of Integers)` - The PBX Type id. - `sbcGateways (Array of Integers)` - The Session Border Controller (SBC) gateways. - `services (Array of Strings)` - Defines the services enabled for the enterprise. Possible values: `PBX`, `Trunk`, `CALLAPP`, `CallRecording`, `SMS`, and `CHAT`. **Response** On a successful request, the API returns a `Long` integer which represents the database ID of the newly created enterprise. This ID will be used in subsequent API calls to associate users and other configurations with this enterprise. **Example Response:** ```json 123456789 ``` ## Part II: Registering the Enterprise At this point, the service provider should present to the Enterprise Admin the **Registration URL** to complete the enterprise registration. Note: The following steps are based on the workflow introduced in the [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) article. ### 1. Retrieve the Registration URL **API Endpoint** - **Method**: `POST` - **Path**: `/enterprise/getActionItemUrl` - **Authentication**: [Reseller-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-resellerlevel-bearer-token) **Request Body** ```json {  "actionType": "REGISTRATION",  "enterpriseName": "string",  "redirectUrl": "string" } ``` **API Response** The API returns a string containing a URL - the **Registration URL**. This URL leads the user to the appropriate Microsoft consent screen. **Example Response For Enterprise Login Action:** ```shell https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=id_token+code&client_id=6a8d4d5b-v334-4db2-9715-90h154ac7043&nonce=6457573502311203778&response_mode=form_post&state=vyTUgEk37BUQK2%2FfDTcvwKoOimF6gl9jC9p2rLlb3Kf0G3utX%2FgBdDa5sD9lZSzGu311s78Z22wamPwcnFZSizl4vMsFyjOCuXA3hnrmYbzBxmo3XLb95XgHh5WSHvXz4DgRqee9qJywqztgI84aQKNCOEAA2tncCoYc%2BtEvNBhBhbXtGd1EIR4V6H1rTOC678nCSCNNKSQWRC2EY0afD7VGstXEKD2QqD%2FrirORkTbkrmxHiQJXd9Y8MzeQxwpcV%2BuVitTxdsdAh0P5F&scope=openid Directory.ReadWrite.All Directory.AccessAsUser.All TeamsAppInstallation.ReadWriteForUser Organization.Read.All User.ReadWrite.All 48ac35b8-9aa8-4d74-927d-1f4a14a0b239/user_impersonation&redirect_uri=https://api.connecttoteams.com/restricted/handleResponse ``` ### 2. Present the **Registration URL** to the Enterprise Global Admin #### a. Display the Registration URL as either a clickable hyperlink or a redirect button in your own portal. When this URL is clicked, the Global Admin is prompted to grant the necessary permissions that enable the Enterprise Portal to function properly by accessing data from Microsoft systems. #### b. Handle the data posted to your provided `redirectURL`. After the Global Admin completes the action on the Microsoft consent screen, the ConnecttoTeams system will post a JSON object to your provided `redirectUrl`. Example JSON object posted: ```json {  "msalAuthenticationResult": {    "authenticationResult": {      "accessToken": "access_token",      "accessTokenType": "login.microsoftonline.com",      "expiresAfter": null,      "expiresOn": 1742985175242681,      "expiresOnDate": null,      "idToken": "id_token",      "multipleResourceRefreshToken": false,      "refreshToken": null,      "userInfo": {        "displayableId": "globaladmin@example.com",        "identityProvider": "user",        "tenantId": "tenantid"      }    },    "resellerId": null,    "tenantId": null  },  "organization": "MSFT",  "officeUserType": "GLOBAL_ADMIN",  "companyAdmin": true,  "containsTeamsTenantAdminAPI": true,  "entAdminAccessToken": "eyJ0eXAiOiJKV1QiLCJhbG......",  "entAdminRefreshToken": "SWIQ7taYgHppd...." } ``` > [!NOTE] > Latest as of ConnecttoTeams 2.18.4 (released 2026-02-14) > > The `entAdminAccessToken` and `entAdminRefreshToken` are provided as part of the `msalAuthenticationResult` object. You may skip step 3 `/enterprise/regenerateAPICredentials`) and use these values instead. > [!NOTE] > Refresh the Access Token > > The access token expires after 60 minutes, and the refresh token expires after 30 days. When the access token expires or is near expiring, it can be refreshed using the refresh token endpoint. See [this link](/v1-api/apidocs/common-api-methods#refresh-enterprise-admin-access-token) for more information about using this endpoint. > > > > Keep in mind that once the refresh token itself expires, a full re-authentication will be required. ### 3. Generate API Credentials for Your Tenant See [Obtaining an Enterprise-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-enterpriselevel-bearer-token). > [!WARNING] > Note > > If you are still using this step, consider updating your implementation to use `entAdminAccessToken` and `entAdminRefreshToken` returned in Step 2 (`msalAuthenticationResult`) to avoid unnecessary API calls. ### 4. Ensure Tenant Admin API is Provisioned #### a. Check “Skype and Teams Tenant Admin API” is Provisioned There are 3 ways to check this. Choose which way is best or easiest for your own implementation. - Call `/provisioning/getO365UserInfo` . See more details in [Common API Methods > Get O365 User Info](/v1-api/apidocs/common-api-methods#get-o365-user-info). If the response contains `containsTeamsTenantAdminAPI": true` , then the “Skype and Teams Tenant Admin API” is provisioned. - Prompt the Enterprise Admin to login to get their MSAL auth token. To do so, repeat the steps outlined in Step 1, substituting `action_type` with `LOGIN_ENTERPRISE_ADMIN`. If the MSAL token provided in the webhook payload contains `containsTeamsTenantAdminAPI": true` , then the “Skype and Teams Tenant Admin API” is provisioned. If the `containsTeamsTenantAdminAPI` field is false, then proceed to provision it. See next step. #### b. Request ConnecttoTeams to provision API credentials for the Enterprise. Only take this step if the above step returns `"containsTeamsTenantAdminAPI": false` . **API Endpoint:** - **Method**: `POST` - **Path**: `/provisioning/provisionTenantAdminAPI` - **Authentication**: [Enterprise-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-enterpriselevel-bearer-token) **Request Body:** ```json {    "authenticationResult": {        "accessToken": "accessToken",        "accessTokenType": "login.microsoftonline.com",        "expiresAfter": null,        "expiresOn": 1752158590229555,        "expiresOnDate": null,        "idToken": "idToken",        "multipleResourceRefreshToken": false,        "refreshToken": null,        "userInfo": {            "displayableId": "globaladmin@example.com",            "identityProvider": "user",            "tenantId": "tenantId"        }    } } ``` ## Part III. Get Consents Each step described here follow the workflow discussed in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) article. ### 1. Getting Mandatory Consents #### i. Get the User Sync Consent Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_USER_SYNC_CONSENT”` and corresponding Consent Type from the Supported Action Types table. #### ii. Get the Presence Sync Consent Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_PRESENCE_CONSENT”` and corresponding Consent Type from the Supported Action Types table. #### iii. Get the “App Deployment Agent“ Consent Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_AGENT_CONSENT”` and corresponding Consent Type from the Supported Action Types table. #### iv. Get the Call App Consent **This is MANDATORY only if you are using the CallApp add-on.** Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_CALL_APP_CONSENT”` and corresponding Consent Type from the Supported Action Types table. #### v. Get the Unified App Consent **This is mandatory only when using the Unified App (recommended) instead of the stand-alone PBX or SMS apps.** If you are still using the stand-alone PBX or SMS apps, consider migrating to the Unified App. Contact our Support team for assistance. Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_UNIFIED_APP_CONSENT”` and corresponding Consent Type from the Supported Action Types table. ### 2. Get “Allow Management by Service Provider” Consent While optional, this consent is **highly recommended**—especially when customers do not have access to the Enterprise Portal. In such cases, the service provider takes on more provisioning tasks, and this consent simplifies ongoing operations. Refer to:: [Granting Consent to Providers to Perform Enterprise Provisioning](/v1/docs/granting-consent-to-providers-to-perform-enterprise-provisioning). #### a. Prompt the Enterprise Admin to consent to Service Provider Management Follow the steps in [Enterprise Admin URL Workflow](/v1-api/apidocs/common-workflow) by using values `action_type` = `“GET_SERVICE_PROVIDER_MANAGEMENT_CONSENT` `”` and corresponding Consent Type from the Supported Action Types table. #### b. Update Enterprise Management Consent By Reseller **API Endpoint** - **Method**: `POST` - **Path**: `/provisioning/updateConsentForEnterpriseManagementByReseller` - **Authentication**: [Enterprise-level Bearer Token](/v1-api/apidocs/getting-started-on-api#obtaining-enterpriselevel-bearer-token) **Request Body** ```json {    "authenticationResult": {        "accessToken": "accessToken",        "accessTokenType": "login.microsoftonline.com",        "expiresAfter": null,        "expiresOn": 1752158590229555,        "expiresOnDate": null,        "idToken": "idToken",        "multipleResourceRefreshToken": false,        "refreshToken": null,        "userInfo": {            "displayableId": "globaladmin@example.com",            "identityProvider": "user",            "tenantId": "tenantId"        }    },    "resellerId": 54,    "tenantId": "tenantId" } ``` **API Response** On success, the API returns ```json 200 OK ``` **On Error** If you encounter this error: `"Unable to complete the consent process as the Roles Teams/Skype Administrator could not be found in the Tenant. Please enable the Roles in your Azure AD and try the Grant Consent process 30mins after enabling the roles"` You must call the `provisionTenantAdminAPI` endpoint to initialize the required roles and permissions. Once this call is completed, retry the consent process. ## Next Steps Proceed to configure the various objects needed for the services used by the Enterprise. For reference, see the following: - [Configuring PBX Connector and Users](/v1-api/apidocs/configuring-pbx-users) - [Configuring CallApp Add-on and Users](/v1-api/apidocs/setting-up-callapp-users) - [Configuring SMS Connector, Users and Groups](/v1-api/apidocs/configuring-sms-users-and-groups)