Blackline API

Prev Next

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.

  1. Sign in to BlackLine and search for API Client Settings.

  2. Under API Credentials Management, click Create Client.

  3. Add the scopes Clarity requests: UsersAPI, TeamsAPI, RolesAPI, plus your instance scope. Add a description such as Clarity.

  4. 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.

  1. Create (or choose) the BlackLine user Clarity will authenticate as.

  2. Edit the user, enable API Access, and give it User Management rights.

  3. 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.