BCCL Documentation
Index

Authentication Issues

BCCL supports three authentication methods: Basic, OAuth (device code flow), and Service-to-Service (S2S). Each method has its own configuration requirements and potential failure points. This page helps you diagnose and resolve authentication problems for all three methods.

Basic Authentication Issues

"401 Unauthorized"

Cause: The username or password is incorrect, or the account is not configured for web service access.

Solutions:

  • Double-check the username and password. For BC cloud (SaaS), you must use a Web Service Access Key, not your regular login password.
  • For on-premises BC, verify that NavUserPassword authentication is configured on the BC server instance.
  • Ensure the BC user account is active and not disabled.
  • If you recently changed your password or access key, update the stored credentials.

Web Service Access Key Has Expired

Cause: Web Service Access Keys in BC cloud have an expiration date.

Solutions:

  • In Business Central, navigate to your user card and generate a new Web Service Access Key.
  • Update the stored credentials in BCCL by running the --remember command with the new key:
  BCCL.EXE --remember --wsurl "https://..." --user "myuser" --password "new-access-key"

On-Premises Authentication Configuration

Cause: The BC server instance is not configured for the expected authentication type.

Solutions:

  • Open the BC Administration tool and verify that the service tier is configured for NavUserPassword authentication.
  • If using Windows authentication, BCCL should use the current Windows credentials automatically.
  • Mixed authentication environments may require specifying the auth method explicitly.

Resetting Stored Credentials

If you suspect stored credentials are corrupted or outdated:

BCCL.EXE --forget

This clears all stored credentials and tokens from BCCL's isolated storage. Then re-enter your credentials:

BCCL.EXE --remember --wsurl "https://..." --user "myuser" --password "mykey"

OAuth Issues

"Device code expired"

Cause: You did not complete the browser authentication within the time limit (typically 15 minutes).

Solutions:

  • Restart the OAuth flow by running the BCCL command again.
  • When the device code appears, open the browser and enter the code promptly.
  • Ensure you are signing in with the correct Microsoft account that has access to the BC environment.

"Invalid client ID"

Cause: The Azure AD App Registration client ID is incorrect or the app does not exist.

Solutions:

  • Verify the client ID in the Azure portal under Azure Active Directory > App registrations.
  • Ensure the app registration has the correct API permissions for Business Central:
    • https://dynamics.microsoft.com/.default or specific BC permissions.
  • The app must have Allow public client flows enabled for device code flow.

Token Expired

Cause: The cached OAuth token has expired (tokens typically last 1 hour).

Solutions:

  • OAuth tokens are not refreshed automatically. After one hour (or after the period predefined by the tenant administrators) a new device code sign-in is required.
  • Run the BCCL command again to start a new device code flow, or use S2S authentication for runs that must outlive the token.

Symptom: The Microsoft sign-in window that BCCL opens reports that admin approval is needed, or asks for consent, and users wonder "what permission am I missing?"

Cause: BCCL requires admin consent in the customer's Microsoft Entra ID (Azure AD) tenant before any user can authenticate with OAuth. This is not caused by one specific missing API permission that a user or MSP can add manually. The requirement is admin consent, granted as a whole.

Solutions:

  • Recommended: in the sign-in window, click the link "Have an admin account? Sign in with that account", sign in with an account that has administrator rights in the tenant, and accept the consent prompt. Consent is then granted for the tenant and normal users can sign in afterwards. Nothing needs to be prepared in the Azure Portal in advance.
  • Alternative: an administrator grants consent in the Azure Portal under Enterprise Applications.
  • No individual permission or scope needs to be hand-picked or requested from your MSP.

See "Admin Consent" in OAuth Authentication.

BCCL Is Not Listed Under Enterprise Applications

Symptom: An administrator looks in the Azure Portal under Enterprise Applications, finds no entry for BCCL, and asks whether the app must be created or registered manually.

Cause: The BCCL application is not listed under Enterprise Applications before consent has been granted. Finding no entry is expected.

Solution: The administrator does not need to create or register an app. Use the "Have an admin account? Sign in with that account" link in the BCCL sign-in window instead; granting consent that way creates the enterprise application entry.

"Insufficient privileges"

Cause: The authenticated user does not have the required permissions in Business Central.

Solutions:

  • Check the BC user's permission sets. The user needs permissions to access the tables and operations you are requesting.
  • For OData operations, the user needs at least the D365 BASIC permission set plus specific table permissions.
  • Verify the user is assigned to the correct company in BC.

Cross-Tenant Authentication

Cause: You are trying to access a BC environment in a different Azure AD tenant.

Solutions:

  • Cross-tenant access requires a Partner license type (not a standard Commercial license).
  • The Azure AD app registration must be configured as a multi-tenant application.
  • Specify the target tenant ID in the --tenantid parameter.

S2S (Service-to-Service) Issues

"Invalid client secret"

Cause: The Azure AD client secret is incorrect or has expired.

Solutions:

  • Client secrets have expiration dates. Check the Azure portal under your App Registration > Certificates & secrets.
  • Generate a new client secret and update BCCL:
  BCCL.EXE --remember --auth S2S --clientid "..." --clientsecret "new-secret" --tenantid "..." --wsurl "..."
  • Copy the secret value immediately after creation -- Azure only shows it once.

"Tenant not found"

Cause: The tenant ID GUID is incorrect or the tenant does not exist.

Solutions:

  • Verify the tenant ID. You can find it in the Azure portal under Azure Active Directory > Overview.
  • The tenant ID is a GUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  • Do not confuse the tenant ID with the BC environment name or the app registration ID.

"Application not authorized"

Cause: The Azure AD application has not been granted permissions in Business Central.

Solutions:

  • In Business Central, go to Microsoft Entra Applications (older versions: Azure Active Directory Applications) and add your app's client ID.
  • Assign the appropriate permission sets to the application entry.
  • Ensure the application entry is Enabled and that its permission-set lines cover the tables BCCL will access.
  • For API access, the app needs the API.ReadWrite.All permission or equivalent BC-specific permissions.

"The server has rejected the client credentials"

Symptom: Fetching data with a Client ID, Tenant ID, and Secret Value supplied by the Business Central owner fails with:

An error has occurred: The server has rejected the client credentials.

Cause: A long-standing bug in Business Central itself, not in BCCL. The registered application in Business Central appears enabled and correctly configured, but the server still rejects the credentials.

Solution: The Enable/Disable state of the application entry in Business Central must be cycled by someone with access to the tenant:

  1. Open the Application Card (the Microsoft Entra / AAD Application entry) for the registered application in Business Central.
  2. Disable the application (turn off the Enabled state).
  3. Close the Application Card window completely.
  4. Re-open the Application Card.
  5. Enable the application again.

Simply toggling the field without closing and re-opening the window is not sufficient. The credentials do not need to be re-issued; the same Client ID, Tenant ID, and Secret Value are reused after cycling.

Why a successful Postman test does not rule this out: being able to obtain a token with the same Client ID, Tenant ID, and Secret Value from an external tool such as Postman does not mean the setup is complete or that the values are wrong on the BCCL side. A correct-looking Application Card plus a working external token request can coexist with this error, because the cause is the BC-side enable state. Do not spend time re-issuing secrets or re-checking IDs before performing the enable/disable cycle.

If the party configuring BCCL has no access to Business Central (a partner or third-party integrator who only received the credentials), the cycle must be requested from and carried out by the Business Central owner. A copy-paste-ready version of these steps is in "Setup Instructions for the Business Central Owner" in Service-to-Service Authentication.

If the enable/disable cycle does not help: e-mail support@hougaard.com with a screenshot of the error as it appears in context, showing the surrounding screen or page in which the error is raised, not just the error text. The context is required to diagnose further.

"Sorry, the current permissions prevented the action"

Cause: Authentication succeeded, but the Entra application lacks a Business Central permission set for the table named in the error. With S2S, all data access runs under the Entra application, so the permission sets that matter are the ones assigned to it on the Microsoft Entra Applications page in BC, including permission sets from third-party apps whose tables BCCL reads (for example LSCentralPermissions for LS Central). See Permission Errors.

"Cannot continue without a user for Business Central (-u --user) or authenticated with --auth"

Symptom:

An error has occurred: Cannot continue without a user for Business Central (-u --user) or authenticated with --auth

Cause: BCCL has no usable credentials for the call: no user (-u/--user) was supplied and no --auth authentication was in effect. The most common cause in scripts is that the --auth S2S parameters and the -w ... --remember endpoint are on separate BCCL command lines, or the script contains more than one --remember line. --remember stores only the parameters given on that one command line; settings spread across several invocations do not accumulate.

Solution: Combine everything into one single command line that includes --auth S2S, --clientid, --clientsecret, --tenantid, -w <endpoint>, and --remember. Reduce multiple --remember lines to one line holding all parameters. Correct the layout everywhere, including in scripts that have worked previously, rather than re-trying. See "Correct Script Layout" in Service-to-Service Authentication.

This error is unrelated to the "Version mismatch" error: fixing the client version does not fix a split --remember layout, and vice versa.

"Unauthorized The credentials provided are incorrect" Part-Way Through a Transfer

Symptom: A large getdata run inserts records for a while (Sql table <name>, 1000 inserted, 0 updated, ...) and then fails with An error has occurred: Unauthorized The credentials provided are incorrect, possibly repeating.

Cause: Because the error appears after successful batches rather than immediately, it points to token expiry, not to wrong credentials. The access token expired during the transfer and BCCL could not renew it because the credentials were not available to the getdata command itself.

Solutions:

  1. Supply the full set of authentication parameters (--auth S2S --clientid ... --clientsecret "..." --tenantid ...) on the getdata command line so BCCL can renew the token during the run.
  2. If the error persists, measure how many minutes elapse from the start of the transfer until the error, and compare with the token lifetime configured in Entra ID.
  3. BCCL renews the S2S token once about 80% of its reported lifetime has elapsed (roughly 48 minutes for a 1-hour token). If your tenant issues very short-lived tokens, the token can expire before the renewal.
  4. For short-lived tokens, use the bccl.exe from the BCCL3 beta (https://www.hougaard.com/on-premises/BCCL/beta/), which handles them better.

See Running Long or Unattended Transfers Reliably.

Token Refresh for Long-Running Operations

Cause: An S2S token expires during a long-running data transfer.

Solutions:

  • BCCL refreshes S2S tokens automatically during the run, provided the S2S parameters are available to the running command (on the command line or remembered on that machine).
  • Put all parameters on one command line for long runs rather than a --remember command followed by a task-only command.
  • If you are still seeing token expiration errors, check whether the tenant issues short-lived tokens (see the previous entry).
  • Break the operation into smaller batches using filters or a smaller page size.

Service Mode Configuration

Cause: BCCL running as a Windows service has incorrect S2S credentials.

Solutions:

  • Check the bccl_service.json configuration file for correct S2S credentials.
  • Verify the file contains valid clientid, clientsecret, tenantid, and wsurl values.
  • Restart the BCCL service after updating the configuration file.
  • Check Windows Event Viewer for detailed error messages from the BCCL service.

General Authentication Troubleshooting

Enable Verbose Mode

The single most useful diagnostic step for authentication problems is to enable verbose mode:

BCCL.EXE -v -t getdata -s table=18 -o test.json

The -v flag causes BCCL to output detailed information about the authentication flow, including:

  • Which credentials are being used (source: command line, remembered, service config).
  • The authentication endpoint being contacted.
  • Token request and response details (with secrets redacted).
  • HTTP status codes for each request.

Check Remembered Settings

If you previously saved credentials with --remember, you can verify they are working by running a simple test command:

BCCL.EXE -t tables -s name=Customer

If this returns results, your credentials are valid. If it fails, re-run --remember after fixing the credential issue.

Clear All Stored Data

To start fresh with a clean slate:

BCCL.EXE --forget

This removes all stored credentials, tokens, and settings from BCCL's isolated storage. You will need to re-enter everything.

Windows Event Viewer (Service Mode)

When BCCL runs as a Windows service, authentication errors are logged to:

Windows Event Viewer > Windows Logs > Application

Filter by source BCCL to see relevant entries. Error events include detailed messages about authentication failures.

Authentication Method Comparison

Feature Basic OAuth S2S
Interactive login No Yes (first time) No
Unattended operation Yes Yes (after initial auth) Yes
Token auto-refresh N/A No Yes (renewed at about 80% of the token lifetime during a run)
Multi-tenant No With Partner license With Partner license
Azure AD app required No Yes Yes
BC cloud support Yes Yes Yes
BC on-premises support Yes Depends on config Depends on config
Recommended for automation No Limited Yes
Recommended for development Yes Yes No

Quick Resolution Checklist

  1. Enable verbose mode (-v) and check the output.
  2. Verify the web service URL is correct and reachable from a browser.
  3. Check credentials -- are they current and correctly entered?
  4. Clear stored data with --forget and re-enter credentials with --remember.
  5. Check BC user permissions -- does the user have access to the required tables?
  6. Check Azure AD configuration (OAuth/S2S) -- app registration, permissions, secrets.
  7. Review Event Viewer (service mode) for detailed error messages.