Bulk provision organizations using the Organization Provisioning Tool

NAVIGATION  Access path: Download the required files from the Provisioning package section of this article.

PERMISSIONS  Partner Administrator or Partner Agent role with Permit access to web services enabled

Overview

The Dark Web ID Organization Provisioning Tool allows partners to provision multiple organizations in bulk using the Dark Web ID External API. Partners enter the required data in a provisioning file, and the tool creates the required organizations, users, and configuration settings in a single process.

Provisioning package

Download the files required to bulk provision organizations.

File Description
Provisioning Data Template Use this spreadsheet to enter the organizations and configuration settings that you want to provision.
Organization Provisioning Script Run this Python script to create organizations and apply the settings defined in the provisioning file.

README File

Contains setup instructions, configuration requirements, command examples, input file requirements, authentication requirements, and troubleshooting information.

Prerequisites

Before using the Organization Provisioning Tool, complete the following requirements.

Prepare a partner user account

The Organization Provisioning Tool uses a partner user account to authenticate to Dark Web ID. The account must have either the Partner Administrator or Partner Agent role and must have Permit access to web services enabled.

Before running the provisioning script:

  1. Create a user account in the partner organization where you want to provision organizations.

  2. Assign either the Partner Administrator or Partner Agent role to the account.

  3. Enable Permit access to web services.

  4. In the account's IP Address Whitelist field, add the public IPv4 address from which the provisioning script will connect to Dark Web ID.

The account is ready to use with the Organization Provisioning Tool.

NOTE  The IP address added to the whitelist must be the public IP address from which the provisioning script connects to Dark Web ID. The address must be included in the partner's Dark Web ID IP whitelist.

Verify the system requirements

Requirement Description
Python 3.9 or later Required to run the provisioning script. To verify the installed version, run python --version.
requests library Required for API communication

openpyxl library

Required to process Excel files

API credentials

Email and password for a partner user account with the Partner Administrator or Partner Agent role and Permit access to web services enabled.

IP allow list

The IP address of the system running the script must be included in the account's IP Address Whitelist.

Provisioning data file

The script accepts .xlsx and .csv files.

The script uses HTTP Basic Authentication with a Base64-encoded username and password. API access is secured through IP address whitelisting; two-factor authentication is not required.

Provisioning file

The provisioning file defines the organizations and settings that the tool will process. Each row represents one organization.

Start with the Provisioning Data Template. The template contains the supported column headers, an example row, and field guidance.

Column headers are matched without regard to capitalization, and surrounding spaces are ignored. For example,Organization Title and organization title are treated as the same column.

Organization

Column Required Accepted values
Organization Title

Yes

 Any text, up to 128 characters.
Industry

Yes

 Select one of the supported values in the Industry values section.

Employee Count

Yes

1-10, 11-50, 51-100, 101-250, or 251+

Domain monitoring

Column Required Notes
Domain

Yes

 Enter the organization's fully qualified domain name (FQDN), such as example.com. If domain setup fails, the tool skips user creation and all subsequent steps for that organization. A domain cannot already be monitored by another Dark Web ID organization. Monitoring of certain domains may be restricted. In some cases, proof of ownership or authorization to monitor the domain may be required.

User

The User fields define the user account that the tool creates for each organization. These fields are separate from the partner user account used to run the provisioning script.

Column Required Notes
User Email

Yes

 Must be globally unique
User First Name

Yes

 User's first name

User Last Name

Yes

User's last name

User Account Type

No

Standard is the default. Privileged is also supported.

Organization-level notifications

Column Required Notes
Notification Preference

No

Never is the default. Supported values:

  • Never

  • Monthly and Daily

  • Monthly

Notification Date Format

Conditional

 M/D/Y is the default. D-M-Y is also supported. Required when Notification Preference is not Never or when Clean Bill of Health is enabled.

Notification Emails

Conditional

Enter one or more comma-separated email addresses. Required when Notification Preference is not Never.

Clean Bill of Health

No

No is the default. Set to Yes to enable Clean Bill of Health notifications.

CBoH Emails

Conditional

Enter one or more comma-separated email addresses. Required when Clean Bill of Health is Yes.

CBoH Reply-To

No

Enter one email address.

User-level preferences

Column Required Notes
User Notification Preference

No

 Daily and Monthly is the default. Monthly and Never are also supported.
User Date Format

No

 M/D/Y is the default. D-M-Y is also supported.

Reporting preferences

IMPORTANT  Organizations created through the Dark Web ID user interface enable all report sections by default except Report Dark Web Benefits. If report section fields are left blank in the provisioning file, the organization's reporting configuration may differ from the default Dark Web ID configuration, and some report sections may be disabled. If automated reports are enabled and all report sections are disabled, monthly and quarterly reports may contain only the first page, with omitted sections indicated in the report output.

Column Required Notes
Report Date Format

No

 M/D/Y is the default. D-M-Y is also supported.
Report Executive Summary No No is the default. This field must be set to Yes if any report subsection is set to Yes.
Report Benchmark Averages No No is the default. Set to Yes to include this section.
Report Monitoring No No is the default. Set to Yes to include this section.
Report Organizational Compromises No No is the default. Set to Yes to include this section.
Report Breaches No No is the default. Set to Yes to include this section.

Report Dark Web Benefits

No

No is the default. Set to Yes to include this section.

Automated reports

Column Required Notes
Automated Report

No

No is the default. Set to Yes to enable automated reports for the organization. When Automated Report is Yes:

  • At least one of Monthly Business Report or Quarterly Business Report must be Yes.

  • Monthly and Quarterly reports can both be enabled.

Monthly Business Report Conditional No is the default. At least one of Monthly Business Report or Quarterly Business Report must be Yes when Automated Report is Yes.
Quarterly Business Report Conditional No is the default. At least one of Monthly Business Report or Quarterly Business Report must be Yes when Automated Report is Yes.
Automated Report Recipients Conditional (required when Automated Report = Yes) Enter one or more comma-separated email addresses.
Automated Report Subject Conditional (required when Automated Report = Yes) Supports [report_type], [start_date], [end_date], and [link].
Automated Report Body Conditional (required when Automated Report = Yes) Enter plain text. The script Base64 encodes the value automatically. Supports [report_type], [start_date], [end_date], and [link].

Industry values

Value Value Value
Aerospace & Defense

Finance & Insurance

 Non-Profit Organization
Business & Professional Services High-Tech & IT Pharmaceutical
Construction & Engineering Hospitality Retail & eCommerce
Education & Research Legal Service Provider
Energy & Transportation Manufacturing State/Local Government
Federal Government Media & Entertainment Systems Integrator

 

Medical & Healthcare

Wireless Industry

 

 

Other

Industry values are matched without regard to capitalization. For example, Other, other, and OTHER are treated as the same value.

How to...

To install the Python libraries required by the provisioning script, complete the following steps:

  1. Open Command Prompt, PowerShell, or a terminal.

  2. Run the following command: pip install requests openpyxl

The requests and openpyxl libraries are installed.

To prepare a provisioning file, complete the following steps:

  1. Download the Provisioning Data Template.

  2. Copy the template to the folder where you want to maintain the provisioning data.

  3. Open the template in Microsoft Excel or another compatible spreadsheet application.

  4. Delete the example organization from the Provisioning Data sheet.

  5. Enter one organization per row.

  6. Complete all required organization and user fields.

  7. Configure any optional notification, reporting, user preference, or automated report settings.

  8. Save the completed file as an .xlsx file.

The provisioning file is ready for validation

Use the --dry-run option before provisioning organizations. A dry run validates all rows and previews the provisioning plan without making API calls. If validation finds problems, the tool reports all detected errors before any organizations are created. This allows you to correct multiple problems before running the provisioning process.

To validate the provisioning file, complete the following steps:

  1. Open Command Prompt, PowerShell, or a terminal.

  2. Navigate to the folder containing provision_organizations.py.

  3. Run the following command, replacing the sample values with your URL, API credentials, and provisioning file path:

    python provision_organizations.py --url https://secure.darkwebid.com/ --username api_user@yourcompany.com --password YourAPIPassword --file provisioning_data.xlsx --dry-run

    ``

  4. Review the validation results displayed in the command-line window.

  5. Correct all reported errors in the provisioning file.

  6. Repeat the dry run until the file passes validation.

The provisioning file is validated and ready to process.

IMPORTANT  Commands containing a password may be retained in shell history. Follow your organization’s credential-handling requirements when entering API credentials.

The provisioning script and provisioning data file can be stored in any folder. The --file argument accepts an absolute path or a path relative to the current directory.

By default, the results spreadsheet is written to the same directory as the file supplied with --file. Use --output to specify another location.

To provision organizations, complete the following steps:

  1. Open Command Prompt, PowerShell, or a terminal.

  2. Navigate to the folder containing provision_organizations.py.

  3. Run the command appropriate for the operating system.

Windows Command Prompt

  1. python provision_organizations.py ^

  2. --url https://secure.darkwebid.com/ ^

  3. --username api_user@yourcompany.com ^

  4. --password YourAPIPassword ^

  5. --file provisioning_data.xlsx

Windows PowerShell

  1. python provision_organizations.py `

  2. --url https://secure.darkwebid.com/`

  3. --username api_user@yourcompany.com `

  4. --password YourAPIPassword `

  5. --file provisioning_data.xlsx

macOS or Linux

  1. python3 provision_organizations.py \

  2. --url https://secure.darkwebid.com/ \

  3. --username api_user@yourcompany.com \

  4. --password YourAPIPassword \

  5. --file provisioning_data.xlsx

4. Monitor the progress displayed in the command-line window.

The tool processes each organization in sequence. If a step fails for an organization, the remaining steps for that organization are skipped, and processing continues with the next row.

Every provisioning run, except a dry run, generates a results spreadsheet and a log file. By default, both files are written to the same folder as the provisioning data file and include the same timestamp.

Example file names:

  1. provisioning_results_YYYYMMDD_HHMMSS.xlsx

  2. provisioning_log_YYYYMMDD_HHMMSS.txt

Results spreadsheet

The results spreadsheet is updated after each organization is processed. Completed results are preserved if the script is interrupted during a run.

Field Description

#

Row number from the provisioning file
Organization Title Organization name
Organization ID Numeric organization ID returned when organization creation succeeds

Step 1 through Step 7

Status of each provisioning step: OK, FAIL, SKIPPED, or N/A

User ID

Numeric ID of the user account created during provisioning

Overall Status

Overall SUCCESS or FAILED status for the organization

Errors

Error messages recorded for the organization, one per line

The spreadsheet uses the following status colors:

Color Meaning

Green

Step completed successfully.
Red Step failed.
Yellow Step was skipped because an earlier step failed.

Gray

Step was not applicable.

Log file

The log file is a plain-text record of the provisioning run. It is written line by line so that available information remains readable if the script is interrupted.

The log includes:

  • Input and output file paths

  • Target tenant URL

  • Organization count and start time

  • Processing progress

  • Per-organization information

  • API request details

  • HTTP response status codes and response times

  • Error responses

  • Retry attempts

  • Final success and failure totals

  • Total elapsed time

The script displays the log file location when the run starts and again in the final summary. Use the log file to investigate provisioning failures or interrupted runs.

By default, the results spreadsheet is saved in the same folder as the provisioning data file. To save the results to a different file, include the --output option:

python provision_organizations.py --url https://secure.darkwebid.com/ --username api_user@yourcompany.com --password YourAPIPassword --file provisioning_data.xlsx --output C:\Reports\results.xlsx

The tool accepts UTF-8 .csv files containing the same headers as the Provisioning Data Template. A byte order mark (BOM) is handled automatically.

To export the Provisioning Data Template as a CSV file, select File > Save As > CSV UTF-8 (Comma delimited) in Microsoft Excel.

To use a CSV provisioning file, provide the CSV file with the --file option:

  1. python provision_organizations.py --url https://secure.darkwebid.com/ --username api_user@yourcompany.com --password YourAPIPassword --file provisioning_data.csv

To display all available command-line options, run:

python provision_organizations.py --help

Command-line reference

Required options

Option Value Description

--url

URL

Base URL of the Dark Web ID tenant. Include the trailing slash. Example: https://secure.darkwebid.com/
--username

EMAIL

 API username or email address
--password

PASS

 API password
--file

PATH

 Path to an .xlsx or .csv provisioning data file

Optional

Option Value Description

--output

 PATH Path for the results spreadsheet. The default is a timestamped results file in the same directory as the provisioning data file.
--delay SECONDS Pause between organizations to reduce the likelihood of API rate limiting. The default is 2.0. Set to 0 to disable the delay.
--dry-run None Validate the provisioning file and display the provisioning plan without making API calls.
--help None Display the command-line help.

Troubleshoot Provisioning Issues

The following issues may prevent successful provisioning:

Error or issue Likely cause Resolution
HTTP 401 Invalid credentials

The API username or password is incorrect.

 Verify the values provided with --username and --password.

HTTP 403 Forbidden

The IP address is not included in the account's IP Address Whitelist, or the user account does not have the required API permissions or access to the target entity.

Verify the account's IP allow-list configuration and confirm that the account has Permit access to web services enabled and access to the required entities.

HTTP 422 during organization creation

One or more field values are invalid.

Review the Errors column in the results spreadsheet.

HTTP 422 with “not a valid domain”

The submitted domain is not accepted or is not a valid FQDN.

Verify that the organization's domain is entered correctly and meets the provisioning requirements.

HTTP 422 with “already monitored”

The domain is already being monitored.

Use a different domain or remove the existing monitored domain before trying again.

HTTP 422 during user creation

The user email address is already in use.

Use a globally unique email address.

HTTP 422 with “The subject field is required”

Automated reports are enabled, but Automated Report Subject is blank.

Enter an Automated Report Subject for every row where Automated Report is Yes.

HTTP 404 during user preference configuration: all retries exhausted

User record synchronization did not complete before the retry limit was reached.

Increase the delay between organizations using --delay. The organization may have been created even if the user preferences were not applied.

Connection timeout after several successful organizations

Rapid successive requests may have triggered API rate limiting.

Increase the delay between organizations, for example by adding --delay 5.

Validation fails before API calls

Required columns are missing or contain unsupported values.

Review the complete validation error list and correct the provisioning file.

The script stops during a run

The process was interrupted or terminated.

Open the generated provisioning_log_*.txt file to review activity up to the interruption.

FAQ

Yes. Enter one organization per row in the provisioning file. The tool processes the rows sequentially.

The tool marks the failed step as FAIL, skips the remaining steps for that organization, and continues processing the remaining rows.

Run the provisioning script with the --dry-run option. The tool validates the complete file and previews the provisioning plan without making API calls.

By default, the results spreadsheet and log file are saved in the same folder as the provisioning data file. Use --output to specify another location for the results spreadsheet.

Yes. The tool accepts .xlsx and UTF-8 .csv files containing the supported column headers.