> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ConnectByOAuth # Package: calendar # Namespace: ExternalCalendarService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-o-auth.md ## Permission Scopes: Manage External Calendars: SCOPE.DC-BOOKINGS.MANAGE-EXTERNAL-CALENDARS Manage External Calendars: SCOPE.DC-BOOKINGS.MANAGE-EXTERNAL-CALENDARS ## Introduction Connects a [Wix schedule](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/introduction.md) to an external calendar account following [OAuth authorization protocol](https://oauth.net/2/). --- ## REST API ### Schema ``` Method: connectByOAuth Description: Connects a [Wix schedule](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/introduction.md) to an external calendar account following [OAuth authorization protocol](https://oauth.net/2/). ### Authorization flow The full authorization flow looks like this: 1. Call *Connect By OAuth* with the appropriate parameters. 2. Redirect the owner of the external calendar account to the returned `oAUthUrl`. 3. The account owner authorizes access. 4. The account owner is automatically redirected to the URL you've provided in `redirectUrl` of the *Connect By OAuth* call. 5. Save the new `connectionId`. You find it as a query parameter in the URL to which the account owner is redirected. See this [sample flow](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/sample-flows.md) for more details. ### Failure consequences If the attempt to connect fails, the account owner is still redirected to the URL you specify in `redirectUrl`, but it incudes an `error` query parameter set to 1 of the following values: - `reject`: The external calendar owner has rejected the authorization request. - `unsupported`: Connecting to the user's external account type is not supported by the provider. - `internal`: An error unrelated to the client or the request that prevents the server from fulfilling the request. ### Next steps After connecting an external calendar account to a Wix schedule, you can do the following. #### Check the 2-way-sync settings Call [List Connections](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-connections.md) and filter by the relevant schedule GUID. If needed, call [Update Sync Config](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/update-sync-config.md) to adjust the syncing configuration. #### Retrieve external calendar events Once a connection is successfully created, you can call [List Events](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events.md) to obtain an up-to-date list of events in the connected external calendars. ### When to call Connect By Credentials instead You can call [Connect By Credentials](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-credentials.md) if: + The external calendar provider doesn't support OAuth. + You don't want to redirect the account owner. Call [List Providers](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-providers.md) for a complete list of external calendar providers supported on the Wix site, including which authorization methods they support. URL: https://www.wixapis.com/bookings/v2/external-calendars/connections:connectByOAuth Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: providerId, scheduleId, redirectUrl Method parameters: param name: providerId | type: providerId | description: GUID of the external calendar provider. Find this with the [List Providers](#list-providers) endpoint. | required: true param name: redirectUrl | type: redirectUrl | description: URL to redirect the user to after they authorize access to the external calendar account. If the connection is successfully established, the user is redirected to this URL with a query parameter `connectionId` containing the new connection GUID. If the attempt to connect fails, the user is redirected to this URL with a query parameter `error` containing the error type. | required: true param name: scheduleId | type: scheduleId | description: GUID of the schedule to connect with the external calendar account. | required: true Return type: ConnectByOAuthResponse - name: oauthUrl | type: string | description: URL of the external calendar authorization page to redirect the user to. Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: NOT_SUPPORTED_BY_PROVIDER | Description: The external calendar provider doesn't support this operation. Use a different connection method or provider. ``` ### Examples ### Connect with an external calendar by OAuth ```curl curl -X POST 'https://www.wixapis.com/bookings/v2/external-calendars/connections:connectByOAuth' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ --data-raw '{ "providerId": "6c533722-f1f9-4847-95c7-d4c4922ae9b0", "scheduleId": "3e47ec65-2975-447c-a7ed-75041e850d5e", "redirectUrl": "https://mysite.com/oauth_completed" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.calendar.ExternalCalendarService.connectByOAuth(providerId, scheduleId, redirectUrl) Description: Connects a [Wix schedule](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/introduction.md) to an external calendar account following [OAuth authorization protocol](https://oauth.net/2/). ### Authorization flow The full authorization flow looks like this: 1. Call *Connect By OAuth* with the appropriate parameters. 2. Redirect the owner of the external calendar account to the returned `oAUthUrl`. 3. The account owner authorizes access. 4. The account owner is automatically redirected to the URL you've provided in `redirectUrl` of the *Connect By OAuth* call. 5. Save the new `connectionId`. You find it as a query parameter in the URL to which the account owner is redirected. See this [sample flow](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/sample-flows.md) for more details. ### Failure consequences If the attempt to connect fails, the account owner is still redirected to the URL you specify in `redirectUrl`, but it incudes an `error` query parameter set to 1 of the following values: - `reject`: The external calendar owner has rejected the authorization request. - `unsupported`: Connecting to the user's external account type is not supported by the provider. - `internal`: An error unrelated to the client or the request that prevents the server from fulfilling the request. ### Next steps After connecting an external calendar account to a Wix schedule, you can do the following. #### Check the 2-way-sync settings Call [List Connections](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-connections.md) and filter by the relevant schedule GUID. If needed, call [Update Sync Config](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/update-sync-config.md) to adjust the syncing configuration. #### Retrieve external calendar events Once a connection is successfully created, you can call [List Events](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events.md) to obtain an up-to-date list of events in the connected external calendars. ### When to call Connect By Credentials instead You can call [Connect By Credentials](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/connect-by-credentials.md) if: + The external calendar provider doesn't support OAuth. + You don't want to redirect the account owner. Call [List Providers](https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-providers.md) for a complete list of external calendar providers supported on the Wix site, including which authorization methods they support. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: providerId, scheduleId, redirectUrl Method parameters: param name: providerId | type: string | description: GUID of the external calendar provider. Find this with the `listProviders()` function. | required: true param name: redirectUrl | type: string | description: URL to redirect the user to after they authorize access to the external calendar account. If the connection is successfully established, the user is redirected to this URL with a query parameter `connectionId` containing the new connection GUID. If the attempt to connect fails, the user is redirected to this URL with a query parameter `error` containing the error type. | required: true param name: scheduleId | type: string | description: GUID of the schedule to connect with the external calendar account. | required: true Return type: PROMISE - name: oauthUrl | type: string | description: URL of the external calendar authorization page to redirect the user to. Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: NOT_SUPPORTED_BY_PROVIDER | Description: The external calendar provider doesn't support this operation. Use a different connection method or provider. ``` ### Examples ### connectByOAuth ```javascript import { externalCalendars } from '@wix/bookings'; async function connectByOAuth(providerId,scheduleId,redirectUrl) { const response = await externalCalendars.connectByOAuth(providerId,scheduleId,redirectUrl); }; ``` ### connectByOAuth (with elevated permissions) ```javascript import { externalCalendars } from '@wix/bookings'; import { auth } from '@wix/essentials'; async function myConnectByOAuthMethod(providerId,scheduleId,redirectUrl) { const elevatedConnectByOAuth = auth.elevate(externalCalendars.connectByOAuth); const response = await elevatedConnectByOAuth(providerId,scheduleId,redirectUrl); } ``` ### connectByOAuth (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { externalCalendars } from '@wix/bookings'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { externalCalendars }, // Include the auth strategy and host as relevant }); async function connectByOAuth(providerId,scheduleId,redirectUrl) { const response = await myWixClient.externalCalendars.connectByOAuth(providerId,scheduleId,redirectUrl); }; ``` ---