Authentication

Bing Webmaster Tools signs API calls with an API key. One key belongs to your Microsoft account and covers every site you can access in Bing Webmaster Tools.

Log inCopy Anchor Link

$ bwt auth login
Log in with your Bing Webmaster Tools API key (one key covers all your sites):
  1. Opening https://www.bing.com/webmasters
  2. Go to Settings (gear icon) > API Access > API Key, then Generate or copy your key.
  3. Paste it below. Input is hidden.
Bing Webmaster API key:
Logged in (profile "default"). Found 1 site; default site is https://www.example.com/ (change with: bwt sites use SITE).

What happens:

1. In a terminal, bwt opens Bing Webmaster Tools and reads the key from a hidden prompt. Piped input is read from stdin instead, so scripts work too.
2. The key is checked with one GetUserSites call before anything is saved. If Bing rejects it, nothing is saved. A newly generated key can take about 30 minutes to start working; --no-verify saves it without the check.
3. The key goes into the OS keychain: macOS Keychain, Windows Credential Manager, or the Secret Service on Linux. Without a keychain, login stops unless you pass --insecure-storage, which keeps the key in a plaintext file with 0600 permissions.
4. A default site is chosen: your only site, a numbered pick when you have several, or none under --no-input (set one later with bwt sites use SITE).

Without saving anything (CI and agents)Copy Anchor Link

BWT_API_KEY=... bwt sites list -o json                       # one command, nothing stored
printf '%s' "$KEY" | bwt auth login --no-input --profile ci  # or save it to a named profile

Prefer the environment variable or stdin over --api-key, which can end up in your shell history.

Several accounts or clientsCopy Anchor Link

Each profile is a separate login:

bwt auth login --profile client-b    # add a profile
bwt auth list                        # list profiles (never shows secrets)
bwt --profile client-b sites list    # use one for a single command
bwt auth use client-b                # change the default profile

BWT_PROFILE also selects a profile. Parallel commands are safe: each profile has its own keychain entry, and login and logout take a per-profile lock. Keychain entries are namespaced by config file, so separate configs (BWT_CONFIG) never overwrite each other's keys.

Credential precedenceCopy Anchor Link

--access-token > BWT_ACCESS_TOKEN > --api-key > BWT_API_KEY > the selected profile. Profiles are chosen by --profile, then BWT_PROFILE, then the saved default.

bwt auth status            # which credential and site are active; no network call
bwt auth status --verify   # plus one GetUserSites check

Bearer tokensCopy Anchor Link

--access-token or BWT_ACCESS_TOKEN sends a bearer token obtained elsewhere, for example from your own OAuth web application. Bearer calls go to www.bing.com, as Bing's OAuth guide shows; BWT_OAUTH_API_HOST=ssl.bing.com switches hosts.

Why there is no browser loginCopy Anchor Link

Bing's OAuth client registration rejects loopback redirect URIs: http://127.0.0.1:47619/callback and http://localhost:47619/callback are both refused as "not a valid http or https url" (checked 2026-10-04). A command-line tool can only receive an OAuth code on the local machine, so browser OAuth would need a public web page that relays codes to the CLI. An API key gives the same access with one copy and paste.

Profiles saved by v0.1.1, which had a browser login, stop working until you run bwt auth login --profile NAME with an API key. Login and logout both delete the old OAuth tokens.

Logging out and rotating the keyCopy Anchor Link

bwt auth logout deletes the saved key from this machine and keeps the profile's site and IndexNow keys. It does not invalidate the key. Bing allows one API key per account, and regenerating it under Settings > API Access invalidates it everywhere; run bwt auth login again on each machine afterwards.

The key travels in the apikey query parameter, as Bing requires. bwt removes it from verbose logs, error messages, and transport errors, and never follows a redirect with it.

TroubleshootingCopy Anchor Link