Permissions
BCCL requires specific permissions in Business Central to function. The extension ships with a dedicated permission set that you must assign to all users who will interact with BCCL, whether through the command-line client or the Business Central UI.
The BCCL Permission Set
BCCL includes a permission set named BCCL (internal ID: 80800). This permission set is automatically available after you install the BCCL extension.
To find it in Business Central:
- Press Alt+Q and search for Permission Sets.
- Look for the permission set with the name BCCL.
This permission set is marked as Assignable = true, meaning you can assign it directly to users through the standard Business Central user setup.
Assigning the Permission Set
Every Business Central user who needs to use BCCL must have the BCCL permission set assigned. This includes:
- Users whose credentials are used by the BCCL command-line client (whether Basic, OAuth, or S2S)
- Users who access the BCCL pages in Business Central (Request Builder, Service Tasks, etc.)
- Service accounts used for S2S authentication
Steps to Assign
- In Business Central, press Alt+Q and search for Users.
- Open the user card for the user who needs BCCL access.
- In the User Permission Sets section, add a new line.
- Set the Permission Set field to BCCL.
- Leave the Company field blank to grant access across all companies, or specify a company name to limit access.
- Close the user card.
Repeat for each user who will use BCCL.
For S2S Authentication
When using Service-to-Service (S2S) authentication, the Azure AD app registration acts as a user in Business Central. You need to:
- In Business Central, search for Microsoft Entra Applications (or Azure Active Directory Applications in older versions).
- Add your app registration's Client ID.
- Assign the BCCL permission set to this application entry.
- Also assign any other permission sets the application needs for the data it will access (for example,
D365 BASICor custom permission sets for specific tables).
Granting the Entra Application Access to Other Apps' Tables
Assigning the BCCL permission set to the Entra application covers BCCL's own objects only. If BCCL has to read data from tables owned by other apps installed in the tenant (ISV or third-party apps such as LS Central, the Shopify Connector, or any vertical solution), the permission set published by each of those apps must also be added as an extra line on the same Entra application record. Do this for every app whose tables BCCL needs; do not try to extend an existing permission set instead.
If a permission set is missing, BCCL fails at runtime, even though authentication succeeded, with:
Sorry, the current permissions prevented the action. (TableData <object id> <table name> IndirectRead: BCCL)The TableData <object id> <table name> part identifies the table that could not be read, and therefore which app's permission set is missing. Concrete example: reading LS Central data requires LSCentralPermissions; SUPER (Data) works as a worst-case catch-all. Note that this is a BC permission configuration issue, not a BCCL or Entra App Registration issue: changing API permissions or consent on the App Registration in the Entra admin center does not fix it, and neither does editing the end user's permission sets when the call is made by the Entra application. See Permission Errors.
What the Permission Set Grants
The BCCL permission set grants the following permissions. Understanding these helps you assess the security impact and troubleshoot access issues.
Table Data Permissions (RIMD)
RIMD means Read, Insert, Modify, Delete. These permissions are granted on all BCCL-specific tables:
| Table | Purpose |
|---|---|
| BCCL Cache | Temporary storage for paged data transfers |
| BCCL Field Mapping | Stores field mapping configurations used in the Request Builder |
| BCCL Request | Tracks individual request executions |
| BCCL Request Task | Defines available request types |
| BCCL Request Type | Request type configuration |
| Service Agent | Tracks registered service agents and their status |
| Service Task | Defines Service Task configurations |
| Service Task Field Mapping | Stores field mapping for Service Tasks |
| Service Task Log | Logs Service Task execution history |
| BCCL Test Table | Used for testing BCCL functionality |
Codeunit Execute Permissions (X)
Execute permission is granted on all BCCL codeunits:
| Codeunit | Purpose |
|---|---|
| BCCL Web Service | The SOAP endpoint that receives requests from the client |
| BCCL Management | Core request handling and routing |
| BCCL Initialization | Registers built-in request types on startup |
| BCCL Data Exchange Output | Formats data for export |
| BCCL Run From Job Queue | Enables Job Queue integration |
| BCCL Request: GETDATA | Handles data export requests |
| BCCL Request: PUTDATA | Handles data import requests |
| BCCL Request: DELETEDATA | Handles record deletion requests |
| BCCL Request: DELETEALL | Handles bulk deletion requests |
| BCCL Request: MASSUPDATE | Handles mass update requests |
| BCCL Request: MAPPING | Generates mapping file templates |
| BCCL Request: TABLES | Searches for tables by name |
| BCCL Request: TASKS | Returns the list of available tasks |
| BCCL Request: CHANGELOG | Reads from the Business Central Change Log |
| BCCL Request: POSTSALES | Posts sales documents |
| BCCL Request: POSTPURCHASE | Posts purchase documents |
| BCCL Request: CODEUNIT | Runs a specified codeunit |
| BCCL Request: DOWNLOAD | Downloads binary data |
| BCCL Request: UPLOAD | Uploads binary data |
| BCCL Request: LEARN | Internal learning/discovery operations |
Page Execute Permissions (X)
Execute permission is granted on all BCCL pages:
| Page | Purpose |
|---|---|
| BCCL | The main BCCL page (entry point) |
| BCCL Request Builder | The graphical command builder |
| Mapping Builder | The visual field mapping editor |
| Service Task Card | Individual Service Task configuration |
| Service Task List | List of all Service Tasks |
| Service Task Clone List | Manages cloned Service Tasks |
| Service Task Subform | Sub-page for Service Task details |
| Request Tasks | List of available request types |
| View Service Task Output | Displays Service Task execution logs |
| Available Agents Factbox | Shows connected service agents |
| BCCL Debug Page | Diagnostic information |
Report Execute Permissions (X)
| Report | Purpose |
|---|---|
| SQL Bundle Builder | Generates SQL replication scripts for multiple tables |
Additional Permissions for Data Access
Important: The BCCL permission set only grants access to BCCL's own objects. It does not grant access to the Business Central data that you want to export or import.
For the BCCL user to read from or write to Business Central tables, the user must also have appropriate permissions on those tables. For example:
- To export data from the Customer table (table 18), the user needs at least Read permission on that table.
- To import data into the Item table (table 27), the user needs Read, Insert, and Modify permissions on that table.
- To delete records from any table, the user needs Delete permission on that table.
You typically achieve this by assigning standard Business Central permission sets (like D365 BASIC, D365 FULL ACCESS, or SUPER) alongside the BCCL permission set. For production environments, it is good practice to create a custom permission set that grants only the specific table-level access your BCCL operations require.
On-Premises Specific Requirements
For on-premises Business Central, there are additional authentication requirements beyond the BCCL permission set:
Web Service Access Key
If you use Basic authentication with the BCCL client, each user must have a Web Service Access Key configured:
- In Business Central, search for Users.
- Open the user card.
- In the Web Service Access section, generate a new Web Service Access Key.
- Use this key as the password (
-pparameter) when running BCCL commands -- not the user's regular login password.
The Web Service Access Key is separate from the user's Windows or NavUserPassword credential. It is specifically for web service authentication.
NavUserPassword Authentication
If your on-premises instance uses NavUserPassword authentication, users authenticate with their Business Central username and password directly. In this case, you use the regular password with the -p parameter.
Verifying Permissions
To verify that a user has the correct permissions:
- Run a simple BCCL command such as:
BCCL -w "<url>" -u <user> -p <password> -t tasks- If the permissions are correct, you will receive a JSON response listing all available task types.
- If you see a permission error, check:
- Is the BCCL permission set assigned to the user?
- For on-premises: does the user have a valid Web Service Access Key?
- Does the user have permissions on the target data tables?
Common Permission Errors
| Error | Likely Cause |
|---|---|
You do not have permission to run codeunit BCCL Web Service |
BCCL permission set is not assigned |
You do not have the following permissions on Table X: Read |
User lacks data table permissions |
Sorry, the current permissions prevented the action. (TableData <id> <table> IndirectRead: BCCL) |
The Entra application (S2S) lacks the permission set of the app that owns the table; add that app's permission set on the Microsoft Entra Applications page. See Permission Errors |
The server returned an error (401) Unauthorized |
Invalid credentials or missing Web Service Access Key |
The server returned an error (403) Forbidden |
User account lacks web service access |
Security Considerations
Principle of Least Privilege
For production environments, consider creating a dedicated BCCL user with only the permissions required for the specific operations you run. Rather than assigning SUPER or D365 FULL ACCESS, create a custom permission set that grants:
- The BCCL permission set
- Read-only access to tables you export from
- Read/Insert/Modify access to tables you import into
- Delete access only to tables where you run delete operations
Auditing
All BCCL operations go through Business Central's standard web service layer. This means:
- Operations are performed as the authenticated user
- Standard Business Central Change Log captures data modifications made through BCCL
- You can audit which user performed which operations through the Change Log
Service Account Best Practices
For automated operations (scheduled tasks, Windows service), create a dedicated service account in Business Central:
- Create a new user specifically for BCCL automation.
- Assign the BCCL permission set.
- Assign the minimum additional permissions needed for the data operations.
- If using S2S, configure the Azure AD app registration with these same permissions.
- Document which operations this account is authorized to perform.