Getting Started

The ConnecttoTeams API is based on an OAuth flow using ClientID/Secret combined with portal login credentials. You use those to obtain a Token, and then you use the Token to perform API actions.

Getting Client ID and Secret

You can obtain a ClientID/Secret pair by opening a Support ticket requesting API access and clientId/secret info.

Create an API Portal Credential

A Admin user for the organization should create a new Admin user to be used for API access. This is the same process as creating a regular admin user.

NOTE: you must login to the Service Portal once using the API admin user because of the mandatory password change on initial login. After changing the password, the API admin user can be used for API authentication.

Getting Started: Obtaining a Token

Once you have your ClientId/Secret and API user credentials, you can use these to obtain a token:

curl --location \
--request POST 'https://api.connecttoteams.com/oauth/token' \
--header 'Authorization: Basic <base-auth-string>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<user>' \
--data-urlencode 'password=<password>' \
--data-urlencode 'grant_type=password'

where <base-auth-string> is a base64 encoding of <client-id>:<client-secret> and the <user> and <password> are the username and password of the API admin user you created.

That request will return an access token as a response.

You will need to know the ResellerId or MasterResellerId in order to perform most requests. You can self-discover your reseller-id using this request:

curl --location --request PUT 'https://api.connecttoteams.com/reseller/getAuthenticatedUser' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data 'myadmin'

This returns a structure like this, which contains your reseller (or master-reseller) ID in the resellerId field:

{
    "username": "myadmin",
    "type": "RESELLER",
    "id": 456,
    "resellerId": 123,
    "registeredAdmin": true,
    "passwordChanged": true,
    "passwordChangedOn": "2020-09-08 07:13:39",
    "email": "[email protected]"
}

Example Requests

Once you have your access token, you can execute some requests.

If you are a Master Reseller, you could use the following request to list all of your Resellers:

curl --location \
--request GET 'https://api.connecttoteams.com/reseller/getResellers/<MasterResellerId>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw ''

A Reseller could use the following request to list all their Enterprises:

curl --location 
--request GET 'https://api.connecttoteams.com//reseller/getEnterprisesForReseller/<ResellerId>' \
--header 'Authorization: Bearer <access_token>' \
--data-raw ''

We are eager to see what solutions our customer use this API for, and as such encourage anyone with questions or a need for guidance to open a ticket.

Provisioning into Teams via Grant Consent

The provisioning/ API endpoints normally require a MSAL authentication token to allow access to the Graph and PowerShell commands needed to push changes into the Teams environment. However, where the Enterprise admin has granted consent for the Service Provider to manage provisioning, it is possible to use the API to push changes all the way into Teams (and avoid the need for the Enterprise admin to login and "sync") for most operations.

How to Determine if Consent Has Been Granted

The /enterprise/getEnterpriseInfoForTenant API call returns an Enterprise object that contains the information needed to determine if this Enterprise has granted the necessary consent. In fact, this information is contained in two places within the returned value:

In the canResellerManageEnterpriseProvisioning boolean field. A true value indicates the necessary consent has been granted.
Inside the array of consent objects in the consentsByEnterprise field. A consent object in that array with the consentName of "EnterpriseManagement" indicates that consent has been granted.

The internals of the API actually checks that both of these conditions are met.

Authentication

The Authentication for using the provisioning/ API as a Reseller involves two steps:

Obtain an authentication token as described above.
Create a special object and use this as the payload in place of the MSALAuthenticationResult described in the provisioning API.

The internal API machinery will validate the Reseller and TenantID along with the reseller authentication token, and will construct an appropriate MSAL token to use with the upstream Microsoft interfaces.

The format of this special object is very simple:

{"tenantId":"<tenant Id>", "resellerId":<reseller Id>}

where the <tenant ID> and <reseller ID> placeholders above would be replaced with the actual tenantId (string) and resellerId (integer) values related to the object of the API call.

Invocation

As an example, suppose you wanted to disable calling for a Teams user.

First, you would obtain an authentication token as described in "Getting Started: Obtaining a Token", above.

Then you could use this to send the following request, filling in the <placeholder> values with the correct values for your situation.

curl --location 'https://api.connecttoteams.com/provisioning/disableCallingForUser/<o365_user_principal_name>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token_from_previous_call>' \
--data '{"tenantId":"<enterprise_tenant_id>","resellerId":<enterprise reseller id>}'

NOTE: Only certain API calls are possible with the permissions available via this mechanism. See the KB article referenced earlier for more info on these limitations. For example, deploying the Teams Apps or granting additional consents will not be possible.

Some of the more common API calls are listed below:

/provisioning/syncTeamsRegistrations (use this to virtually push the "Sync Teams Users" button)

/provisioning/addUser

/provisioning/updateUserDetails

/provisioning/disableUser

/provisioning/deleteUser

/provisioning/restoreUser

/provisioning/disableCallingForUser

/provisioning/enableCallingForUser