About the BWT Connection API

The BWT Connection API connects a site to Bing Webmaster Tools by linking a Microsoft account to it. Once a site is connected, the BWT Site Readiness API can add the site to the Bing account, verify it with Bing, and submit its sitemap.

A site has at most one Bing Webmaster Tools connection, so no method takes a connection ID. The connection is resolved from the site the call is made on.

With the BWT Connection API, you can:

• Start a Bing authorization and retrieve the URL where the person connecting approves it.
• Check whether the site is connected, and whether the current caller owns the connection.
• Disconnect the site from its Bing account.

How connecting works

Connecting is a browser flow that's completed for you:

1. Call Get Connect URL and surface the returned URL to the person connecting. Open it in a top-level browser window or tab, not in a popup that keeps a reference to the page that opened it.
2. The URL opens a Wix page that sends them on to Bing, where they sign in with their Microsoft account and approve access.
3. Bing redirects back to Wix, where the OAuth exchange is completed and the credentials are stored server-side. There's no authorization code for you to exchange, and the API never returns tokens.
4. Poll Get Connection until status is VALID.

While the site has stored credentials (status VALID or INVALID), neither Get Connection nor Get Site Readiness reports when a new authorization finishes: Get Connection keeps reporting the stored credentials, and Get Site Readiness keeps using them until the new ones replace them. To re-authorize or replace the connected Microsoft account in a way you can follow, call Disconnect first, then connect as above. See Connect a site to Bing Webmaster Tools.

Each connect URL is single-use and expires after 2 hours, so request a fresh one for every attempt. Once the person opens it, they must finish on Bing within 10 minutes, in the same browser, while signed in to Wix as the user who called Get Connect URL. Stop polling when that window has passed: an abandoned attempt can keep reporting PENDING for up to 2 hours.

Connection ownership

The connection belongs to the site, but it's owned by the Wix user who authorized it. Get Connection reports whether the current caller is that owner in ownedByCaller. It doesn't identify the connected Microsoft account.

ownedByCaller is meaningful only when status is VALID or INVALID. It's false for any caller without a Wix user identity, so a false value means the caller isn't the owner, not that a particular other Wix user is.

Re-authorizing with the same Microsoft account refreshes the stored credentials. Authorizing with a different Microsoft account replaces the connection. One Microsoft account can be connected to several sites, and each site is connected and disconnected separately.

Before you begin

It's important to note the following points before starting to code:

• The site the call is made on must be published, have a connected domain, and allow search-engine indexing. Otherwise, Get Connect URL fails with FAILED_PRECONDITION (SITE_NOT_PUBLISHED, DOMAIN_NOT_CONNECTED, or SITE_NOT_INDEXABLE).
• Any Microsoft account can be used. Adding the site to the Bing account and verifying it happen after connecting, through the BWT Site Readiness API.
• Starting a connection requires a Wix user identity to own it. Calls without one, such as calls made as an app or with an API key, fail with PERMISSION_DENIED. Any Wix user with SEO permissions can start a connection, not only the site owner.
• Get Connection reads the stored connection and doesn't call Bing, so a connection that was revoked on Microsoft's side can still report VALID. Get Site Readiness checks with Bing, and reports NOT_CONNECTED when Bing no longer accepts the stored credentials.

Use cases

• Connect a site to Bing Webmaster Tools
• Show the site's connection status
• Disconnect a Microsoft account

Terminology

• Connection: The link between a site and a Microsoft account, held as Bing credentials that are stored server-side and never returned.
• Bing account: The Bing Webmaster Tools account of the connected Microsoft account. Sites are added to it and verified with the BWT Site Readiness API after the site is connected.