# Enterprise Conferencing

## Table of contents
- [Background](#background)

- [Prerequisites](#prerequisites)

- [Creating an Organizational Unit link token](#creating-an-organizational-unit-link-token)

- [Organizational Unit OAuth authorization](#organizational-unit-oauth-authorization)

- [Future usage](#future-usage)

## Background
We have introduced a mechanism to authorize enterprise conferencing services like Zoom and Webex
at an Organizational Unit level. This allows multiple accounts to use an enterprise's conferencing provider after a single administrator has set it up, without each account having to authorize independently.

This can be considered as an extension of the existing Enterprise Connect model
for connecting calendars. The reason the model differs is that for the
functionality to work, we need an entity through which to associate the two
enterprise-level connections, eg. calendars and conferencing services, in order
to correlate the two.

We have introduced the concept of Organizational Units for this purpose.

```mermaid
flowchart RL

ou((Organizational Unit))
calendars[Enterprise Connect calendars]
zoom[Zoom Enterprise]

calendars --> ou
zoom --> ou```
Throughout the examples in this document, we have used Zoom as an example of an enterprise conferencing provider. Authorizing other providers, like Webex, are supported by the same approach.

## Prerequisites
We will start with the assumption that your application already has access to a
calendar service account through [Enterprise Connect](/developers/authorization/enterprise-connect/index.md).

```mermaid
flowchart RL

ou((Organizational Unit))
calendars[Enterprise Connect calendars]
zoom[Zoom Enterprise]

calendars -.-> ou
zoom -.-> ou

style ou fill:none
style zoom fill:none```
From this state, an Organizational Unit authorization will be initiated with:

- A token generated to require the authorization process include the
previously authorized calendar service account

- A query string parameter instructing Cronofy that the process must also
authorize an enterprise-level Zoom connection

The administrator will then go through a process where:

- They prove they have administrative access to the existing calendar service
account (if necessary)

- They authorize permission for Cronofy to generate conferencing details for
any user or room within their Zoom account

- They approve the association of the two entities via a new or existing
Organizational Unit within Cronofy

- They are returned to the originating application with a `code` for gaining
tokens for an authorization to the Organizational Unit (optional but
recommended)

## Creating an Organizational Unit link token
Gives the integrating application a way to provide a single-use token that
seeds the authorization flow with constraints.

For example, requiring a previously authorized calendar service account is used
within the Organizational Unit authorization flow as relevant.

This is the example we will document here.

### Example request
```http
POST /v1/organizational_unit_authorization_link_tokens HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json

{
  "service_account_id": "ser_64b17f9b8090ea21640c9151"
}
```

### Request parameters
##### `data_center_url` *(required)*

The URL for the data center you want to communicate with. Possible choices are:

- `api-au.cronofy.com` - Australia
- `api-ca.cronofy.com` - Canada
- `api-de.cronofy.com` - Germany
- `api-sg.cronofy.com` - Singapore
- `api-uk.cronofy.com` - United Kingdom
- `api.cronofy.com` - United States

Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `API_KEY` *(required)*

The `client_secret` of the client.

##### `service_account` *(required)*

A [`String`](/developers/api/data-types/index.md) `sub` value for a service
account already authorized for the OAuth client.

> **INFO:** If you do not know the `sub` for a set of Enterprise Connect tokens you hold,
you can call the [UserInfo endpoint](/developers/api/identity/userinfo/index.md)
using the tokens to discover this information.

### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "organizational_unit_authorization_link_token": {
    "ou_link_token": "{random_string}"
  }
}
```

### Response parameters
##### `organizational_unit_authorization_link_token.ou_link_token`

A short-lived [`String`](/developers/api/data-types/index.md) token to be passed
as a querystring parameter to an [Organizational Unit OAuth authorization flow](#organizational-unit-oauth-authorization).

## Organizational Unit OAuth authorization
To establish a link between a calendar service account and a Zoom account-level
connection, an administrator from the organization needs to pass through an
OAuth authorization flow.

> **WARNING:** The Zoom admin account authorizing the integration *must* be on a paid Zoom plan. Any Zoom service tier other than Free will work.

From an integrators perspective, this is similar to an [Enterprise Connect](/developers/authorization/enterprise-connect/index.md).
authorization flow where an administrator is redirected to a crafted URL within
their browser and later return with a `code` that can be redeemed for OAuth
tokens at the end of the process.

The main difference here is that the resulting authorization will relate to an
Organizational Unit rather than a calendar service account.

### Example request
*Spread over multiple lines for clarity.*

```
https://{data_center_app_url}/organizational_unit_oauth
    ?response_type=code
    &client_id={CLIENT_ID}
    &redirect_uri={REDIRECT_URI}
    &state={STATE}
    &scope=organizational_unit_use_integrations
    &capabilities[]=conferencing
    &ou_link_token={OU_LINK_TOKEN}```
### Request URL parameters
##### `data_center_app_url` *(required)*

The URL for the data center you want to communicate with. Possible choices are:

- `app-au.cronofy.com` - Australia
- `app-ca.cronofy.com` - Canada
- `app-de.cronofy.com` - Germany
- `app-sg.cronofy.com` - Singapore
- `app-uk.cronofy.com` - United Kingdom
- `app.cronofy.com` - United States

Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `scope` *(required)*

`organizational_unit_use_integrations` is the only supported scope at present.

##### `capabilities[]` *(required)*

A single value of `conferencing` to force the administrator to authorize access
to a conferencing provider, such as Zoom, as part of the overall authorization
flow.

##### `ou_link_token` *(required)*

A token referencing the desired calendar service account from
[creating an Organizational Unit link token](#creating-an-organizational-unit-link-token).

##### `conferencing_provider_name` *(optional)*

A optional value when you want the administrator to connect a specific
conferencing provider rather than choosing their preferred one from a list.

Currently supported values are:

- `indeed`

- `webex_enterprise`

- `zoom_enterprise`

- `google_meet`

- `ms_teams`

If a value is provided but not supported or recognized, the flow will default to
showing the list of available conferencing providers.

You can control the providers shown to your users by setting the [conferencing categories](/developers/conferencing-services/categories/index.md).

## Future usage
With the link established, any calendar accounts provisioned via the calendar
service account will be automatically cross-referenced with the enterprise conferencing
service account and appropriate conferencing profiles provisioned when an email-based
match is found.

No further intervention will be required by the integrator or the adminstrator
for this to happen.

Details of conferencing profiles linked in this way will be available through
the [UserInfo endpoint](/developers/api/identity/userinfo/index.md) when
authenticated as the individual accounts.


---
[Read in HTML](/developers/conferencing-services/enterprise-conferencing/)