Getting Started

Introduction

The ConnecttoTeams APIs uses an OAuth authentication flow that combines a Client ID and Secret with portal login credentials. This process generates an access token, which is then required to authenticate and authorize all subsequent API requests.

API Categories

The platform provides a range of API endpoints, grouped into three main categories based on their functionality and authentication requirements. Each category requires specific types of authentication tokens.

Reseller-Level APIs
These APIs are intended for Partners, Master Resellers, or Resellers.
- Authentication Required: Reseller-level bearer token. See Obtaining Reseller-level Bearer Token.
Enterprise-Level APIs
These endpoints are designed for enterprise-related operations.
- Endpoint Prefix: /enterprise
- Authentication Required: Reseller-level bearer token. See Obtaining Reseller-level Bearer Token.
Provisioning APIs
These APIs support user provisioning operations
- Endpoint Prefixes:
  - /provisioning
  - /enterprise/configureUser
  - /valet/configureValetUser
- Authentication Required:
  1. With Enterprise-level Bearer Token and an MSAL object in the request body; or
  2. With Reseller-level Bearer Token using the Service Provider Consent discussed here.
- Special Case for /enterprise/configureUser and /valet/configureValetUser
  - Can be accessed with Reseller-level Bearer Token without an MSAL object.

Obtaining Reseller-level Bearer Token

To use Reseller-level APIs, you'll need to obtain a bearer token using a Client ID, Client Secret, and API Admin credentials. Follow the steps below to get started.

Request Client ID and Secret
You can obtain a ClientID/Secret pair by submitting a Support ticket requesting API access and clientId/secret.
Create a Portal Admin User
1. Create a New Admin User
  * An existing Portal Admin should create a new admin account specifically for API access.
  * This process is identical to creating a regular admin user.
2. Initial Login Required
  * The new API Admin user must log in once to the Service Portal to complete the mandatory password reset.
  * After changing the password, the user account will be ready for API authentication.
Generate a Bearer Token
Once you have your ClientId, Secret and API Admin 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'

Required Fields:

base-auth-string : Base64 encoding of <client-id>:<client-secret>
user : API Admin username
password : API Admin password

The response returns an access_token which you can use in subsequent API requests.

Retrieve Your Master Reseller or Reseller ID

You will need to know the MasterResellerId or ResellerId in order to perform most requests. You can self-discover your this 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": "abc@def.com"
}

Example API Requests

Once you have your access_token, you can begin making API calls.

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 ''

Need Help?

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.

Obtaining Enterprise-level Bearer Token

To authenticate Enterprise-level API calls, you must first register the enterprise and then generate API credentials using the /enterprise/regenerateAPICredentials endpoint.

IMPORTANT
You cannot obtain an Enterprise-level bearer token until the enterprise has been registered.

Attempting to call the endpoint /enterprise/regenerateAPICredentials before enterprise registration will result in an error.
For instructions on how to register an enterprise, see: Part II: Registering the Enterprise.

Generate Enterprise API Credentials

Method: POST

Path: /enterprise/regenerateAPICredentials

Request Body:
Below is the JSON request body for completing the newly created enterprise registration process.

tenantId

Required Fields

tenantId - The Microsoft Tenant ID returned after completing enterprise registration
Authorization : a Reseller-level token (see Obtaining Reseller-level Bearer Token above) must be provided in the request header

Sample cURL Request:

curl --location --request POST 'http://api.connecttoteams.com/enterprise/regenerateAPICredentials' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '<tenantId>'

API Response

{
    "enterpriseId": 124,
    "entAdminUsername": "entAdminUsername",
    "entAdminSecret": "entAdminSecret",
    "clientID": "clientID",
    "clientSecret": "clientSecret"
}

Important
Store the enterprise API credentials in a secure storage location.
These credentials are required to retrieve an enterprise-level access token, which is necessary for making calls to the Provisioning API.
Each time you call regenerateAPICredentials, the previously generated credentials will be invalidated and replaced with new ones. Be sure to update your secure storage accordingly.

Provisioning into Teams via Grant Consent by Reseller

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 the endpoints listed below.

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.

Authenticating as a Consented Reseller

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

Obtain a Reseller-level Bearer Token.
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 ID and Tenant ID 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.

Refreshing the MSAL Authentication Object

For /provisioning endpoints, after the initial authentication, the access token is returned via the MSAL authentication object which has a default token expiry time of 50 minutes.

To avoid token expiration errors, the Provisioning API supports silent token refresh — allowing you to refresh your access token without re-authenticating.

To refresh the MSAL authentication object, use this endpoint with your existing MSAL token object:

/provisioning/getAccessTokenSilently

Provisioning Example

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

First, you would obtain an authentication token as described in Obtaining Reseller-level Bearer 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 this KB article for more info on these limitations. For example, deploying the Teams Apps or granting additional consents will not be possible.