Overview
The Clarity BlackLine connector reads your BlackLine users and their access through BlackLine’s User Management API, and can provision that access back:
What Clarity syncs / writes | BlackLine source | Direction |
|---|---|---|
Users (with active / inactive status) | GET /v1/users | read |
Teams (and team membership) | GET /v1/teams, team hierarchy, team users | read · write |
Entities (company codes) per user | GET /v1/entities, per-user entities | read · write |
Roles within products (role-products) | GET /v1/users/roles-products | read · write |
Six user permission flags (allowUserMentions, allowUserToEditJournalConfig, allowUserToEditIntercompanyConfig, allowAdhocMatching, allowIntercompanySettlement, requiresJournalReviewer) | boolean fields on the user record | read · write |
Create a user | POST /v1/users | write |
Activate / deactivate a user | PUT /v1/users/{id} (isActive) | write |
Role-product entitlements appear in Clarity keyed as {roleId}:{productId}, because BlackLine assigns a role within a product.
Connector version. When you add the integration, choose v2 (Saloon). It imports Teams, Entities, Role-Products and the permission flags, and supports full lifecycle management. The older v1 (Legacy) version does not import or assign roles and is kept only for existing tenants that have not yet migrated.
Authentication
Clarity authenticates with the OAuth 2.0 password grant: it posts to https://{subdomain}.api.blackline.com/connect/token with your API client’s Client ID and Client Secret, plus a BlackLine username and that user’s API key, requesting the scope TeamsAPI UsersAPI RolesAPI {instance_id}. There is no browser consent or redirect step. Tokens last about an hour; BlackLine issues no refresh token, so Clarity simply requests a new one when needed.
BlackLine’s Reporting API is covered by a separate Clarity integration (BlackLine Report) and is not part of this guide.
Prerequisites
A BlackLine administrator who can create API clients and edit users (grant API access, generate API keys).
A dedicated BlackLine service user for Clarity. We recommend this rather than a person’s account, because the API key is tied to that user.
Your BlackLine region / environment and instance ID (Steps 1 and 2).
If you cannot create API clients yourself, BlackLine Support can issue the Client ID and Client Secret for your instance.
BlackLine’s API documentation is at https://developer.blackline.com/ (a BlackLine customer login is required for most of it).
Step 1 — Identify your environment (subdomain)
BlackLine hosts each region on its own API host, https://{subdomain}.api.blackline.com. The Clarity subdomain field takes only the short environment code: not a full hostname, no https://, and no .api.blackline.com.
Environment | subdomain value |
|---|---|
US production | us |
EU production | eu |
Asia-Pacific production | ap |
US sandbox | sbus |
EU sandbox | sbeu |
Asia-Pacific sandbox | sbap |
Any other value is rejected with “BlackLine subdomain”…” is not a valid environment”. If BlackLine has given you a token URL on a different host (for example a tenant-specific xxxx.api.blackline.com), contact your Clarity customer success team before configuring.
Step 2 — Create an API client and note your instance scope
You need an API client (Client ID + Client Secret) that is allowed the UsersAPI, TeamsAPI and RolesAPI scopes and your instance scope.
Sign in to BlackLine and search for API Client Settings.
Under API Credentials Management, click Create Client.
Add the scopes Clarity requests: UsersAPI, TeamsAPI, RolesAPI, plus your instance scope. Add a description such as Clarity.
Click Create Client and copy the Client ID and Client Secret.
Screen and menu names can vary between BlackLine instances. If you don’t see API Client Settings, ask BlackLine Support for a User Management API client for your instance with the scopes above. They will return the Client ID, Client Secret and instance scope.
The instance scope is the value Clarity calls instance_id. Enter it exactly as BlackLine shows it, including its instance_ prefix (for example instance_XXXXXXXX). Clarity appends it to the scope string as-is.
Step 3 — Prepare the service user and generate its API key
The username and password Clarity sends are a BlackLine user’s login ID and API key, not the user’s interactive login password.
Create (or choose) the BlackLine user Clarity will authenticate as.
Edit the user, enable API Access, and give it User Management rights.
Open the user’s User Details and generate an API key.
⚠️ The API key is shown only once, when it is generated. Copy it immediately. If it is lost, generate a new key and update the Clarity integration.
The service user needs:
Read access to users, teams, entities and roles-products. Without it, the sync fails or returns no entitlements. The credential test reads GET /v1/users, so missing UsersAPI access fails the test outright.
Write access to users, teams, entities and roles-products, only if you use Clarity provisioning. Reads succeed without it; grants, revokes, and user create / activate / deactivate will fail.
Step 4 — Enter the credentials in Clarity
In Clarity, add a BlackLine integration, choose the v2 (Saloon) version, and fill in (all fields are required):
Clarity field | Value |
|---|---|
client_id | The Client ID of the API client from Step 2. |
client_secret | The Client Secret of that API client (stored encrypted). |
instance_id | Your instance scope, including the instance_ prefix (Step 2). |
username | The service user’s BlackLine login ID / username (Step 3). |
password | The service user’s API key from User Details (Step 3). Not their login password. Stored encrypted. |
subdomain | Your environment code from Step 1: us, eu, ap, sbus, sbeu or sbap. |
Click Next, this will test the credentials that you provided.

If you plan to use provisioning, we recommend validating a grant, a revoke and a deactivation on a test user first (ideally in a BlackLine sandbox environment) before relying on it for production off-boarding.
Step 5: App Settings
Complete the App Settings form. Details for each field can be found at the following article: Common App Configuration Steps
Step 6: User Settings
Complete the User Settings form. Details for each field can be found at the following article: Common App Configuration Steps
Step 7: Validate Your Selections and Save
Validate the selections from Configure App Step 3, and hit the Save button.
Save Button
Clicking the Save button will trigger the first full sync for your application (even if you selected Manual syncing).
Troubleshooting
Symptom | Likely cause |
|---|---|
“BlackLine subdomain”…” is not a valid environment” | The subdomain field holds a full host, a URL, or an unlisted region. Enter only us, eu, ap, sbus, sbeu or sbap. |
invalid_client on the credential test | Client ID or Client Secret typo, or the client secret was regenerated in BlackLine. |
invalid_grant on the credential test | password holds the user’s login password instead of the API key, the API key was regenerated, or the user lacks API Access or is inactive. |
invalid_scope on the credential test | The API client is not allowed one of UsersAPI, TeamsAPI, RolesAPI, or instance_id is wrong (missing its instance_ prefix, or another instance’s value). |
Test passes but provisioning fails | The service user lacks write / User Management rights. BlackLine also caps writes at 75 requests per minute; Clarity throttles to stay under it. |
What Clarity does NOT do
No user deletion. BlackLine’s API has no user-delete endpoint. Clarity offboards by deactivating the user, which is reversible.
No Reporting API. That is the separate BlackLine Report integration.
No role provisioning on v1 (Legacy). Use v2.
No attribute write-back beyond name, email, login ID and active status on user create. Free-form reference fields and supervisor are not written.
Need Help?
If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.