# Organization Connect - multiple service accounts > **DESIGN** ## 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 additional enterprise calendar connections alongside an existing connection at an Organizational Unit level. This allows an integrator to support multiple calendar providers for a single customer, multiple tenants from a single calendar provider, and of course a combination of those things. This often crops up with larger enterprise customers where different business units may run on different tenants, and potentially even different providers. This can be considered as an extension of the existing Enterprise Connect model for connecting a single calendar tenant. 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. two or more calendar services, in order to provide a single interface across them. We have introduced the concept of Organizational Units for this purpose. ```mermaid flowchart RL ou((Organizational Unit)) calendarsA[Domain A calendars] calendarsB[Domain B calendars] calendarsA -.-> ou calendarsB -.-> ou``` ## 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). This is represented by `Domain A` in the diagrams. ```mermaid flowchart RL ou((Organizational Unit)) calendarsA[Domain A calendars] calendarsB[Domain B calendars] calendarsA -.-> ou calendarsB -.-> ou style ou fill:none style calendarsB 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 `Domain A` calendar service account - A query string parameter instructing Cronofy that the process must also authorize an enterprise-level calendar 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 connect to the additional calendar service 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 an already authorized calendar service account and another calendar service account, an administrator from the organization needs to pass through an OAuth authorization flow. 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_service_accounts &capabilities[]=calendars &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_service_accounts` in order to access multiple Service Accounts via the Organizational Unit. ##### `capabilities[]` *(required)* A single value of `calendars` to force the administrator to authorize access to a calendar provider 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). ##### `provider` *(optional)* A value of either `google` or `ms_graph` which allows you to specify the provider that will be authorized against. ## Future usage With the link established, any attempts to provision calendar accounts through the original calendar service account will attempt to connect through the additional calendar service accounts if necessary. No further intervention will be required by the integrator or the adminstrator for this to happen. --- [Read in HTML](/developers/authorization/organization-connect/multiple-service-accounts/)