Authentication Overview

BCCL supports three authentication methods for connecting to Business Central. Each method is designed for a different scenario, from quick interactive testing to fully automated unattended operations. This page helps you understand which method to use and how authentication works across all BCCL modes.

The Three Authentication Methods

BCCL provides the following ways to authenticate against Business Central:

Method	Flag Value	User Interaction	Best For
Basic Authentication	`--auth Basic`	None (credentials on command line)	On-premises BC, simple testing
OAuth Device Code Flow	`--auth OAuth`	Browser-based login	Cloud BC with interactive user
Service-to-Service (S2S)	`--auth S2S`	None (fully automated)	Cloud BC automation, services

Basic Authentication is the default. If you do not specify the --auth parameter, BCCL assumes Basic.

When to Use Each Method

Basic Authentication

Use Basic Authentication when you are working with:

On-premises Business Central deployments using NavUserPassword or Windows authentication
Simple testing and development where you want to get started quickly
Quick one-off operations against any Business Central instance that supports basic credentials
Docker-based development environments where security is less of a concern

Basic Authentication requires a username (-u) and password (-p). For cloud Business Central, the password must be the user's Web Service Access Key, not their regular login password.

OAuth Device Code Flow

Use OAuth when you are working with:

Cloud Business Central environments where you need interactive user authentication
Ad-hoc operations that you run manually from the command line
Partner scenarios where you need to authenticate against multiple tenants
Situations where you cannot create an Azure AD App Registration

OAuth uses the Device Code Flow, which means BCCL displays a code and URL. You open your browser, enter the code, and log in with your Microsoft account. After authentication, BCCL caches the token for one hour so you do not have to re-authenticate for subsequent commands.

Service-to-Service (S2S) OAuth

Use S2S when you need:

Fully automated and unattended operations with no human interaction
BCCL running as a Windows service in service mode
Scheduled scripts or CI/CD pipelines that run without user input
Long-running operations that may exceed one hour (S2S tokens auto-refresh)
Production cloud environments where Basic Authentication is not recommended

S2S requires an Azure AD (Entra ID) App Registration with a client secret. It authenticates using the OAuth 2.0 client credentials grant, which means no browser interaction is needed.

The --auth Parameter

You control which authentication method BCCL uses with the --auth parameter:

BCCL --auth Basic    (default - username and password)
BCCL --auth OAuth    (interactive browser login)
BCCL --auth S2S      (Azure AD App Registration)

If you omit --auth entirely, BCCL defaults to Basic Authentication.

Connecting to Business Central

Finding Your Web Service URL

Before you can authenticate, you need the BCCL web service URL. You can find this in Business Central:

Open Business Central
Search for Web Services using the search bar (Alt+Q)
Look for the bccl codeunit in the list
Copy the SOAP URL for the codeunit

The URL format depends on your deployment type.

On-Premises URL Format

For on-premises Business Central, the URL typically looks like:

http://bcserver:7047/BC/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl

The components are:

Component	Description
`bcserver`	Your Business Central server hostname
`7047`	The SOAP web services port (default is 7047)
`BC`	The Business Central server instance name
`CRONUS%20Canada%2C%20Inc.`	The company name (URL-encoded)
`Codeunit/bccl`	The BCCL codeunit endpoint

Cloud URL Format

For cloud (SaaS) Business Central, the URL follows this pattern:

https://api.businesscentral.dynamics.com/v2.0/{tenantid}/{environment}/WS/{company}/Codeunit/bccl

Where:

Placeholder	Description
`{tenantid}`	Your Azure AD tenant ID (a GUID)
`{environment}`	The Business Central environment name (e.g., `production`, `sandbox`)
`{company}`	The company name (URL-encoded)

The %1 Placeholder

You can use %1 as a placeholder in your URL instead of the company name:

http://bcserver:7047/BC/WS/%1/Codeunit/bccl

When you use %1, BCCL replaces it with the value of the --defaultcompany setting or the -s defaultcompany= parameter. This is especially useful in service mode where you configure the URL once in bccl_service.json and set the company name separately.

Remembering Your Settings

All three authentication methods work with the --remember flag. When you add --remember to any BCCL command, your connection settings (URL, credentials, authentication method, and other parameters) are stored in user-scoped isolated storage on your machine.

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

After remembering settings, subsequent commands only need the task-specific parameters:

BCCL -t tables

To clear all remembered settings and cached tokens, use --forget:

BCCL --forget

The --forget flag removes both the saved settings file (BCCL/BCCL.Settings.json) and any cached OAuth tokens (BCCL/BCCL.token.json) from isolated storage.

Token Caching and Refresh

BCCL handles authentication tokens differently depending on the method:

Method	Token Behavior
Basic	Credentials sent with every request (Base64-encoded in the Authorization header)
OAuth	Access token cached for 1 hour in isolated storage; subsequent runs reuse the cached token
S2S	Token acquired at startup; during long operations BCCL renews it once about 80% of the token's reported lifetime has elapsed

The S2S token auto-refresh is particularly important for long-running operations like large data exports or SQL replication. BCCL renews the S2S token once about 80% of its reported lifetime has elapsed (roughly 48 minutes for a standard 1-hour token), so S2S operations can run for a long time without timing out, provided the S2S parameters are available to the running command (put them on the same command line as the task for long runs). OAuth, by contrast, cannot be renewed without interaction and also stops working after a period predefined by the tenant administrators, which makes it unsuitable for long or scheduled transfers. See Running Long or Unattended Transfers Reliably.

Note that --remember stores only the parameters given on that one command line; the endpoint, authentication method, and credentials must all be on a single --remember command. See "Rules for --remember" in Command Reference.

Authentication Method Comparison

Feature	Basic	OAuth	S2S
On-premises support	Yes	No	No
Cloud support	Yes (with Web Access Key)	Yes	Yes
User interaction required	No	Yes (first time per hour)	No
Token auto-refresh	N/A	No	Yes
Windows service support	Yes	No	Yes
Scheduled task support	Yes (on-premises)	No	Yes
Azure AD App required	No	No	Yes
Cross-tenant (Partner)	No	Yes	No
Recommended for production	On-premises only	Ad-hoc use	Yes

Quick Start Examples

Basic Authentication (On-Premises)

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

OAuth (Cloud - Interactive)

BCCL --auth OAuth -w "https://api.businesscentral.dynamics.com/v2.0/{tenantid}/{env}/WS/{company}/Codeunit/bccl" -t tables --remember

S2S (Cloud - Automated)

BCCL --auth S2S --clientid "your-app-id" --clientsecret "your-secret" --tenantid "your-tenant-id" -w "https://api.businesscentral.dynamics.com/v2.0/{tenantid}/{env}/WS/{company}/Codeunit/bccl" -t tables --remember

Security Considerations

Never hard-code credentials in shared scripts. Use --remember to store them in isolated storage, or use environment variables.
Prefer S2S over Basic for cloud production environments. Basic Authentication with Web Access Keys is being deprecated by Microsoft for cloud deployments.
Rotate client secrets regularly when using S2S authentication.
Use the principle of least privilege when granting permissions to Azure AD App Registrations.
Credentials stored with --remember are kept in .NET isolated storage, which is scoped to the current user and application. They are not accessible to other users on the same machine.