BCCL Documentation
Index

Basic Authentication

Basic Authentication is the default and simplest way to connect BCCL to Business Central. It uses a username and password (or Web Service Access Key) to authenticate every request. This page explains how to set up Basic Authentication for both on-premises and cloud deployments.

How Basic Authentication Works

When you use Basic Authentication, BCCL combines your username and password, encodes them with Base64 using ISO-8859-1 encoding, and sends them in the HTTP Authorization header with every SOAP request to Business Central:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

This is the standard HTTP Basic Authentication scheme. Because credentials are sent with every request, there is no token to manage, refresh, or cache. The trade-off is that your username and password must be available to BCCL at all times during operation.

Parameters

Basic Authentication uses the following command-line parameters:

Parameter Short Long Description
Web Service URL -w --wsurl The BCCL codeunit web service URL
Username -u --user The Business Central username
Password -p --password The password or Web Service Access Key
Auth method --auth Optional; Basic is the default

Since Basic is the default authentication method, you do not need to specify --auth Basic explicitly. The following two commands are equivalent:

BCCL --auth Basic -w "http://bcserver:7047/BC/WS/CRONUS/Codeunit/bccl" -u demo -p demo -t tables

BCCL -w "http://bcserver:7047/BC/WS/CRONUS/Codeunit/bccl" -u demo -p demo -t tables

On-Premises Authentication

For on-premises Business Central configured with NavUserPassword authentication, you use the Business Central user's credentials directly:

BCCL -w "http://bcserver:7047/BC/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -u myuser -p MyP@ssw0rd -t tables

The username and password are the same credentials the user would use to log in to the Business Central web client.

Windows Authentication

If your on-premises Business Central is configured with Windows authentication, you can use Windows domain credentials:

BCCL -w "http://bcserver:7047/BC/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -u DOMAIN\myuser -p MyP@ssw0rd -t tables

Make sure the Windows user has the appropriate permissions in Business Central, including the BCCL permission set.

Cloud Authentication with Web Service Access Key

For cloud (SaaS) Business Central, the -p parameter must be the user's Web Service Access Key, not their regular login password. Regular Microsoft 365 passwords do not work with Basic Authentication against cloud Business Central.

Finding Your Web Service Access Key

  1. Open Business Central in your browser
  2. Navigate to My Settings (click the gear icon in the top right)
  3. Look for Web Service Access Key or search for User Card
  4. On the User Card, find the Web Service Access Key field
  5. If no key exists, generate one by clicking the assist button on the field

Example: Cloud Basic Authentication

BCCL -w "https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/production/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -u myuser@contoso.com -p "YourWebServiceAccessKeyHere" -t tables

Important: Microsoft is phasing out Web Service Access Keys for cloud Business Central. For production cloud environments, consider using Service-to-Service Authentication instead.

Remembering Credentials

Typing the full connection string and credentials for every command is tedious and error-prone. The --remember flag saves all current parameters to isolated storage so you can omit them on subsequent runs.

Saving Your Settings

Run your command once with --remember:

BCCL -w "http://bcserver:7047/BC/WS/CRONUS/Codeunit/bccl" -u demo -p demo --remember

BCCL stores your settings in a file called BCCL/BCCL.Settings.json inside .NET user-scoped isolated storage. The storage location is determined by the operating system and is specific to the current user account and the BCCL application.

Using Remembered Settings

After remembering, you only need to provide task-specific parameters:

BCCL -t tables
BCCL -t getdata -s table=18 -f json -o customers.json
BCCL -t getdata -s table=27 -f csv -o items.csv

BCCL loads your remembered URL, username, and password automatically. If you provide a parameter on the command line that was also remembered, the command-line value takes precedence.

Overriding Remembered Settings

You can override any remembered parameter by specifying it on the command line. This is meant for occasional interactive use; it does not make --remember suitable for multi-company or parallel runs, where every command should carry all its parameters (see Replicating Multiple Companies). For example, to temporarily use a different user:

BCCL -u otheruser -p otherpassword -t tables

The remembered settings remain unchanged. Only the parameters you explicitly provide are overridden for that single run.

Forgetting Settings

To clear all remembered settings and remove stored credentials:

BCCL --forget

This deletes both the settings file (BCCL/BCCL.Settings.json) and any cached authentication tokens (BCCL/BCCL.token.json). Use this when switching between environments or when you want to ensure no credentials remain on the machine.

Complete Example: First-Time Setup

Here is a typical workflow for setting up Basic Authentication for the first time:

  1. Find the web service URL in Business Central under Web Services (look for the bccl codeunit SOAP URL)
  2. Test the connection with a simple command:
   BCCL -w "http://bcserver:7047/BC/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -u demo -p demo -t tables

If successful, you see a list of available tables.

  1. Remember the settings so you do not have to retype them:
   BCCL -w "http://bcserver:7047/BC/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -u demo -p demo --remember
  1. Run subsequent commands without connection details:
   BCCL -t tables
   BCCL -t getdata -s table=18 -f json

Using Basic Authentication in Service Mode

When running BCCL as a Windows service, you configure Basic Authentication in the bccl_service.json file instead of command-line parameters:

{
  "agentid": "REMOTEBCCL1",
  "auth": "basic",
  "url": "http://bc22:7047/BC/WS/%1/Codeunit/bccl",
  "user": "demo",
  "password": "MyPassword",
  "defaultcompany": "CRONUS Canada, Inc.",
  "verbose": "true"
}

Note the use of %1 in the URL, which BCCL replaces with the defaultcompany value at runtime. This allows you to define the company name in one place.

Security Considerations

  • Credentials are Base64-encoded, not encrypted. Base64 is a reversible encoding, not encryption. Anyone who intercepts the HTTP traffic can decode the credentials. Always use HTTPS for cloud connections.
  • Use HTTPS whenever possible. For on-premises deployments, configure your Business Central server to use SSL/TLS on the web services port.
  • Isolated storage is user-scoped. Settings stored with --remember are only accessible to the current Windows user account running BCCL. Other users on the same machine cannot read them.
  • Avoid embedding passwords in scripts. Instead of putting the password directly in a batch file or shell script, use --remember to store credentials once, then reference them implicitly in your scripts.
  • Rotate Web Service Access Keys periodically. If you are using Basic Authentication with cloud Business Central, regenerate the Web Service Access Key on a regular schedule and update your remembered settings.

Limitations

  • Not recommended for cloud production environments. Microsoft is moving away from Basic Authentication for cloud Business Central. Use S2S Authentication for cloud production workloads.
  • No token refresh. Unlike S2S, there is no automatic token refresh mechanism. If your Business Central session times out during a very long operation, you may need to retry.
  • Credentials sent with every request. Each SOAP call includes the full credentials in the header, increasing exposure compared to token-based methods.

Troubleshooting

Problem Solution
"401 Unauthorized" error Verify username and password are correct. For cloud BC, ensure you are using the Web Service Access Key, not the login password.
"404 Not Found" error Check that the URL is correct. Verify the BCCL codeunit is published in Web Services.
Connection refused Verify the server hostname and port. For on-premises, ensure the BC SOAP web services port (default 7047) is open.
"Cannot continue without a user" You have not provided -u and no username was remembered. Run with -u and -p.
"Cannot continue without a password" You have not provided -p and no password was remembered. Run with -p.

For more detailed troubleshooting, add --verbose (-v) to your command to see detailed diagnostic output, including the authentication method being used and any HTTP errors.