Enterprise Admin URL Workflow

This guide describes how to retrieve and use action-specific URLs for Enterprise Admins to complete registration, login, or grant consent for Microsoft Teams integrations. These URLs are retrieved using the getActionItemUrl API and are essential for enabling various Teams-based services through the ConnecttoTeams platform.

Overview

You can generate URLs for the following admin actions:

Enterprise registration
Enterprise admin login
Microsoft Teams service consents (e.g., user sync, presence, call recording)

These URLs are presented to the Enterprise Global Admin (GA), who completes the action. The outcome is returned to your application via a webhook or redirect URL, depending on the action type.

Supported Action Types

This table outlines the valid actionType values and corresponding content type for the enterprise/getActionItemUrl endpoint.

Action Type	Consent Type	Use
`REGISTRATION`	-	To get the URL with which the Global Admin (GA) can start the enterprise registration process. When registration is completed, an msalAuthentication token is given to the webhook. This token can be used to access other Graph API calls, such as for deploying apps to MS Teams.
`LOGIN_ENTERPRISE_ADMIN`		To get the URL with which the Global Admin (GA) can login to the system thereby getting their msalAuthentication token. This token can be used to access other Graph API calls, such as for deploying apps to MS Teams. Retrieving the URL for this actionType may be frequently done during deployment of app and, if GA is not consenting to “Allow Management by Service Provider“, during actions like Sync Teams Users.
`GET_USER_SYNC_CONSENT`	`UserSync`	MANDATORY To get the URL to which the GA can consent to accessing and updating the MS Teams users data. This is needed for configuring services to Teams Users such as PBX and SMS.
`GET_PRESENCE_CONSENT`	`Presence`	MANDATORY for calling services To get the URL with which the GA can consent to access Presence status of Teams users. The presence status is used in the following services: PBX Connector CallApp Add-on Call Recording Add-on
`GET_CALL_APP_CONSENT`	`Valet`	MANDATORY for CallApp Add-on To get the URL with which the GA can consent to access MS Teams in order for CallApp Add-on to function.
`GET_CONTACTS_CONSENT`	`Contacts`	OPTIONAL To get the URL with which the GA can consent to allow sync’ing with Outlook and Microsoft Organization contacts. Useful for contacts management feature of the following apps: PBX Connector CallApp Add-on SMS Connector
`GET_CDR_CONSENT`	`CDR`	OPTIONAL To get the URL with which the GA can consent to allow access to call records in Teams. Useful to allow Service Provider to get more call details to debug call issues.
`GET_CALL_RECORDING_CONSENT`	`CallRecording`	MANDATORY for Call Recording Add-on To get the URL with which the GA can consent to access MS Teams in order for Call Recording to function. This includes creating the Compliance Recording Policy in the Microsoft Teams tenant.
`GET_SERVICE_PROVIDER_MANAGEMENT_CONSENT`	`EnterpriseManagement`	OPTIONAL To get the URL with which the GA consent to allow Service Provider to do most management tasks on GA’s behalf. This includes provisioning users, syncing users, and create direct routes among others.
`GET_AGENT_CONSENT`	`Agent`	MANDATORY To get the URL with which the GA can grant consent for deploying the app to organization’s Teams app catalog, as well as accessing Teams user, channels and group chat. This consent is essential for successful app deployment and proper functionality.

Retrieve the action URL

API Endpoint

Method: POST

Path: /enterprise/getActionItemUrl

Token to use: Reseller-level Bearer Token

Request Body (JSON)

{
  "actionType": "<actionType>",
  "enterpriseName": "<enterpriseName>",
  "redirectUrl": "<redirectUrl>"
}

Required Fields

actionType - see Action Type Values table above.

enterpriseName

redirectUrl - Your webhook URL that will receive the response payload

API Response

The API returns a string containing a URL. This URL leads the user to the appropriate Microsoft consent screen.

Sample cURL Request

curl --silent --location --request POST 'https://api.connecttoteams.com/enterprise/getActionItemUrl' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
  "actionType": "REGISTRATION",
  "redirectUrl": "https://yourapp.com/callback",
  "enterpriseName": "AcmeCorp"
}'

Sample Response

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=id_token+code&client_id=<client_id>&nonce=6457573502311203778&response_mode=form_post&state=<state>&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

Present the URL to the Enterprise Global Admin
Display the retrieved URL in step 1 as either a clickable hyperlink or a redirect button in your own portal.

When this URL is clicked, the Global Admin is prompted to follow the actions presented — such as consenting to some permissions.

Handle the data posted to your provided `redirectURL`.

a. For Registration & Login, a JSON object is posted to the provided redirectUrl after the process is completed.

Sample JSON Object Response on Registration or Login Actions:

{
  "msalAuthenticationResult": {
    "authenticationResult": {
      "accessToken": "eyJ0eXAiOiJKV1QiLCJub25j...",
      "accessTokenType": "login.microsoftonline.com",
      "expiresAfter": null,
      "expiresOn": 1742985175242681,
      "expiresOnDate": null,
      "idToken": "rZ7VeEm5tG2nlBZ6MAfW-...",
      "multipleResourceRefreshToken": false,
      "refreshToken": null,
      "userInfo": {
        "displayableId": "admin@example.com",
        "identityProvider": "user",
        "tenantId": "5c0068f3-dfbb-..."
      }
    },
    "resellerId": null,
    "tenantId": null
  },
  "organization": "MSFT",
  "officeUserType": "GLOBAL_ADMIN",
  "companyAdmin": true,
  "containsTeamsTenantAdminAPI": true
}

b. For other consent actions, a message is sent as a query parameter, and the user is redirected to the provided redirect URL.

Sample Redirect on Success:

https://yourapp.com/callback?success=User Sync Consent Completed Successfully

Sample Redirect on Error:

https://yourapp.com/callback?error=Unable to Complete the process. User is not a Global Admin

Query parameter values are displayed without URL encoding for better readability.

If action has an applicable consent type, update App Consent for the Enterprise

Method: POST

Path: /provisioning/updateAppConsent/{type}

Token to use: Enterprise-level Bearer Token

Request Body (JSON)

{
  "authenticationResult": {
    "authenticationResult": {
      "accessToken": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IjdKbXh..............",
      "accessTokenType": "login.microsoftonline.com",
      "expiresOn": 1743285790991831,
      "idToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1..............",
      "multipleResourceRefreshToken": false,
      "userInfo": {
        "displayableId": "user@example.com",
        "identityProvider": "user",
        "tenantId": "tenantId"
      }
    }
  }
}

Required Fields

type : The string value related to the consent granted. The possible values are CDR, Presence, UserSync, EnterpriseManagement, Valet, Agent, Contacts, CallRecording