--- title: "Blackline API" slug: "blackline-api" description: "This guide covers what a BlackLine administrator must configure in their instance, and which values to enter into Clarity." tags: ["Integrations", "How-To"] status: "new" updated: 2026-11-18T15:22:42Z published: 2026-11-18T15:22:42Z canonical: "help.claritysecurity.com/blackline-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.claritysecurity.com/llms.txt > Use this file to discover all available pages before exploring further. # Blackline API ## 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/](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. ![](https://cdn.document360.io/2d020999-1823-4d4d-b6d2-4b52fb4a9617/Images/Documentation/image-5FBCJUN8.png?sv=2026-02-06&spr=https&st=2026-11-19T02%3A15%3A14Z&se=2026-11-19T03%3A15%3A14Z&sr=b&sp=r&sig=v7qtfzYXg40ZSsB19I1sIxU8osErWzkQGtg%2BWRb%2Futc%3D) **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](/home/docs/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](/home/docs/common-app-configuration-steps) ## Step 7: Validate Your Selections and Save Validate the selections from Configure App Step 3, and hit the **Save** button. > [!NOTE] > 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](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST. ## Related - [Blackline Report as a Service](/blackline-report-as-a-service.md)