# Enterprise Connect Enterprise Connect is an alternative way for applications to obtain authorization to access users' calendars. Instead of each end-user giving authorization individually, a **Service Account** is used to obtain authorization programmatically. The flow to obtain authorization on an organization level looks like this: **Service Account authorization flow** Sequence diagram of Service Account authorization in eight steps between your application, a customer's IT admin, Cronofy and their calendar service, ending with your application storing an access token for the Service Account. ```mermaid sequenceDiagram autonumber participant Your Application participant Cronofy actor IT admin participant Calendar service IT admin->>Calendar service: Create a Service Account with permissions Your Application->>Cronofy: Send IT admin to authorization page with scope IT admin->>Calendar service: Log in as the Service Account and approve Calendar service->>Cronofy: Access granted Cronofy->>Your Application: Redirect IT admin back with code Your Application->>Cronofy: Redeem code Cronofy-->>Your Application: access_token, refresh_token and service_account_id Your Application->>Your Application: Store Service Account tokens ``` 1. The customer's IT admin creates a Service Account on their calendar service, configured with the permissions and restrictions they want. 2. Your application sends the IT admin to Cronofy's hosted authorization page, specifying the permissions it needs on their organization's calendars as the `scope`. 3. The IT admin logs in to the calendar service as the Service Account and approves access. 4. The calendar service grants Cronofy access through the Service Account. 5. Cronofy redirects the IT admin back to your application with a `code` on the query string. 6. Your application redeems the `code` with Cronofy. 7. Cronofy returns an `access_token`, a `refresh_token` and a `service_account_id` to your application. 8. Your application stores the Service Account's tokens. It uses the `access_token` to request delegated access to the calendars of users and resources in the organization. ## The authorization process To get started, you will need the following: - A web application - A `client_id` and `client_secret` for your application from the Cronofy Developer Dashboard - A Service Account on a Google Workspace, Microsoft 365, or On-premise Exchange installation configured to access one or more user mailboxes. Once you have these you are then in a position to proceed with the first stage of authorization which is for the Service Account. More details below but this process is modelled as an OAuth2 flow. You redirect from your application to an authorization page and which in return redirects back to your application with a `code` for subsequent `access_token` redemption. Once you have an `access_token` for a Service Account you then use that to request individual `access_tokens` for user and resource calendars. You then store and use the `access_tokens` in exactly the same way with the Cronofy API as you do with those generated through direct end-user authorization. ## Service Accounts Service Accounts are organization level accounts that can be created in both Microsoft and Google Workspace domains. They can be granted permissions on a set of mailboxes within the domain. They can also be given permissions to access Resource Calendars (eg meeting rooms) and Shared Mailboxes. A Service Account can be used to: - [Request Delegated Access](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/delegated-access/index.md) to user's calendars, resource calendar or shared mailbox calendar. - [List Resource calendars](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/list-resources/index.md) available to the Service Account. It can't be used to access calendars or events of its own. The [Enterprise Connect - Guide for System Administrators](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-guide/index.md) gives more information on how to setup and configure Service Accounts. ## Service Account authorization As described above, obtaining an authorization for a Service Account is modelled as an OAuth2 flow. The outcome of this flow is an `access_token` for the Service Account. The [documentation](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/request-authorization/index.md) describes the full set of parameters but of particular note are `scope` and `delegated_scope` . `scope` refers to the permissions you are requesting that directly apply to the Service Account. For instance if you want access to User mailboxes you would request `service_account/accounts/manage` and if you also want Resource Calendars then you would add `service_account/resources/manage` . These are presented as a space separated list. `delegated_scope` refers to the maximum set of possible permissions your application will need for the User and Resource calendars. These are similar to the scope values you would request as part of direct end-user authorization. ## User and resource calendar account authorization Once you have a Service Account authorization, you can then request access to an individual User or Resource Calendar. This is similar to an OAuth flow but without user involvement. The diagram below shows how you can obtain a `code` for a user or resource, which can then be exchanged for an `access_token`, which is used to authenticate user-specifc or resource-specific requests to the Cronofy API. **Delegated access flow** Sequence diagram of delegated access in five steps between your application and Cronofy, repeated for each user or resource calendar, ending with your application storing an access token for that calendar. ```mermaid sequenceDiagram autonumber participant Your Application participant Cronofy loop For each user or resource Your Application->>Cronofy: Request delegated access with email, scope and callback_url Cronofy->>Your Application: Send code to callback_url Your Application->>Cronofy: Redeem code Cronofy-->>Your Application: access_token, refresh_token and sub Your Application->>Your Application: Store tokens end ``` 1. Your application requests delegated access from Cronofy, authenticated with the Service Account's `access_token`, giving the user or resource's email, the permissions it needs as the `scope`, and a `callback_url`. This begins the steps repeated for each user or resource. 2. Cronofy sends a `code` to the `callback_url`. 3. Your application redeems the `code` with Cronofy. 4. Cronofy returns an `access_token`, a `refresh_token` and a `sub` value to your application. 5. Your application stores the tokens. It uses the `access_token` to access the user or resource's calendar, and the `refresh_token` to get a new `access_token` when one expires. This ends the repeated steps. A [request for Delegated Access](https://docs.cronofy.com/api-reference/authorization/enterprise-connect/delegated-access/index.md) is made which has similar parameters to an OAuth2 authorization. The `redirect_uri` is replaced by a `callback_url`. The `callback_url` will need to be publicly accessible so during development we recommend using a service like [ngrok](https://ngrok.com/). The `code` is returned to this `callback_url` and an [Access Token Request](https://docs.cronofy.com/api-reference/authorization/individual-connect/request-token/index.md) is made with the code. Again, replace `redirect_uri` with `callback_url`. ```json { "client_id": "{CLIENT_ID}", "client_secret": "{CLIENT_SECRET}", "grant_type": "authorization_code", "code": "{CODE}", "callback_url": "{CALLBACK_URL}" } ``` You can then store the `access_token` and `refresh_token` returned against the user in your application. ## Refreshing access tokens obtained through Enterprise Connect This is identical to the process for tokens generated by end-user authorization. [Refresh an Access Token](https://docs.cronofy.com/api-reference/authorization/individual-connect/refresh-token/index.md). ## Using access tokens obtained through Enterprise Connect We've designed the Enterprise Connect process to ensure you can use the tokens generated with the Cronofy API in exactly the same way as those generated by end-user authorization. ## Revoking user authorization When a user wants to terminate their service, you will need to revoke the authorization between their account and your application. This can be done by calling the [Revoke Authorization](https://docs.cronofy.com/api-reference/authorization/individual-connect/revoke/index.md) API endpoint. ## Supported platforms Enterprise Connect currently supports the following platforms: - [On-premise Exchange](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-office365-exchange/index.md) - [Google](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-gsuite/index.md) - [Google - Free/Busy](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-gsuite/free-busy-access-mode/index.md) - [Microsoft 365](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-office365-graph/index.md) - [Microsoft 365 - Free/Busy](https://docs.cronofy.com/connect/calendar-admins/enterprise-connect-office365-graph/free-busy-access-mode/index.md) --- [Read in HTML](https://docs.cronofy.com/developers/temporal-grid/connectivity/enterprise-connect/)