Creating and Registering an Enterprise with Restricted Access

  • Updated on Jan 12, 2026
  • Published on Jun 22, 2025
  • 6 minute(s) read
Prev Next

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

Sample API response

[
  {
    "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

Sample API Response

[
  {
    "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

Sample API Request Body

Below is the JSON request body for creating a new enterprise. Required fields are highlighted and explained in detail.

{
  "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:

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 article.

1. Retrieve the Registration URL

API Endpoint

Request Body

{
  "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:

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:

{
  "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
}

3. Generate API Credentials for Your Tenant

See Obtaining an Enterprise-level Bearer Token.

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.
    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:

Request Body:

{
    "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 article.

1. Getting Mandatory Consents

i. Get the User Sync Consent

Follow the steps in Enterprise Admin URL 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 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 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 by using values  action_type = “GET_CALL_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.

a. Prompt the Enterprise Admin to consent to Service Provider Management

Follow the steps in Enterprise Admin URL 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

Request Body

{
    "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

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: