> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumos.com/llms.txt > Use this file to discover all available pages before exploring further. # Blackline ## After this article You'll be able to connect BlackLine to Lumos to sync and provision users, entities, roles, and team memberships. ## Capabilities | Functionality | Type | Sync | Provision | Description | | :- | :- | :- | :- | :- | | Users | Account | Yes | Yes | User account records | | Entities | Permission | Yes | Yes | Entities in BlackLine | | Roles | Permission | Yes | Yes | Role definitions | | Teams | Permission | Yes | Yes | Team memberships in BlackLine | | Team-scoped roles | Permission | Yes | No | Each role a user holds, paired with each team they're in. Only synced when **Team-Scoped Roles** is on. Request or remove the role itself to change access. | | Deprovisioning Action | Type | Description | | :- | :- | :- | | Deactivate | User | Deactivate a user in BlackLine | | Delete | User | Delete (deprovision) the user | ## Required plan and roles * **BlackLine role:** the connecting user must be a BlackLine **admin with API Access enabled** (in BlackLine terms, a System Administrator with the API role). * **OAuth credentials:** BlackLine issues OAuth client credentials through its customer support team. Request them and they'll return an installation form with your Client ID, Client Secret, and Scope. Required API features are user management and master data (the scopes below). * **Scopes:** the token request must include `bl.users`, `bl.mdm`, and your instance-specific scope `instance_{InstanceGUID}` (for example, `bl.users bl.mdm instance_`). The instance GUID is environment-specific. Find it in BlackLine under **System** > **API Client Settings**, or on the support-provided installation form. Lumos requires only `bl.users` and `bl.mdm` as base scopes. * **Permission scoping:** this integration can only be connected with **full provisioning access enabled**. There's no read-only mode. ## Read-only access vs provisioning **Is read-only possible?** No. BlackLine can only be connected with full provisioning access enabled, there's no read-only mode for this connector. **What full provisioning requires.** OAuth client credentials issued by BlackLine support (Client ID and Client Secret) with the `bl.users` and `bl.mdm` scopes plus your instance-specific `instance_{InstanceGUID}` scope, a self-service API Key for the integration user, and a BlackLine admin with API Access enabled to request and use the credentials. Follow the steps below to gather and enter these values. **Watch out for.** The instance scope goes in the Scopes field as `instance_`, not the Tenant Identifier field, which takes only the bare GUID and isn't sent in the token request. Mixing these up produces an `invalid_grant: Invalid instance GUID` error even when the Client ID and Secret are valid. ## Instructions **Phase 1: Gather BlackLine values** 1. Request OAuth 2.0 credentials from BlackLine support if you don't have them. The installation form contains the **Client ID**, **Client Secret**, and the **Scope** string (including your `instance_` GUID). 2. Generate a BlackLine user **API Key** (self-service in the BlackLine app) for the integration user. 3. Note the **Username** of the BlackLine application user selected to use the API. 4. Determine your **Region** from your BlackLine subdomain: `us` for `us.blackline.com`, `eu` for `eu.blackline.com`, `apac` for `ap.blackline.com`. **Phase 2: Connect in Lumos** 1. Find the BlackLine card in your Lumos integrations (reconnect an existing card or add a new one). 2. Enter the **Client ID**, **Client Secret**, **API Key**, and **Username**. 3. In **Scopes**, enter the full scope string including the instance scope: `bl.users bl.mdm instance_{InstanceGUID}`. 4. In **Tenant Identifier**, enter the **bare instance GUID** (without the `instance_` prefix). The Tenant Identifier is used for app identification only and isn't sent in the OAuth token request, so the instance scope must go in the Scopes field. 5. Select the **Region**, and check **Sandbox** if you're connecting a sandbox BlackLine instance. 6. Optionally, check **Team-Scoped Roles** (off by default). See [Team-scoped roles](#team-scoped-roles) below. 7. Click **Connect**. ### Team-scoped roles Turn on **Team-Scoped Roles** if you want Access Reviews in Lumos to match BlackLine's user access report. When it's on, Lumos syncs one extra entitlement per role, product, and team, for example `Preparer - Finance - Account` (the Preparer role on Accounts, in the Finance team). Lumos still syncs the global role entitlements (for example, `Account - Preparer`). Team-scoped roles are added alongside them. Keep these limits in mind: * **Team-scoped roles are inferred.** BlackLine's API doesn't report which team a role applies to. Lumos pairs every role a user holds with every team they're in, the same way BlackLine's user access report lists access. Lumos can't show a user as an Approver in one team but not another. * **Subroles aren't supported.** No BlackLine API exposes subroles, so Lumos doesn't sync them. * **Team-scoped roles are for review only.** You can't request or remove them in Lumos. To change a user's access, request or remove the role itself. * **Changes apply on the next sync.** Turning the setting on starts syncing team-scoped roles on the next sync. Turning it off stops syncing them. ## API Endpoints Used The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them. ## Troubleshooting **Connection fails with a generic error even though the API key is valid.** The most common cause is a scope misconfiguration. The underlying BlackLine error is often `invalid_grant: Invalid instance GUID` from `/connect/token`, which means the instance scope is missing or wrong. Fix it by setting **Scopes** to include both `bl.users` and `instance_` (plus `bl.mdm`), putting the **bare GUID** (no `instance_` prefix) in the Tenant Identifier field, and confirming the Client ID/Secret come from the same **System > API Client Settings** page (same instance) as the GUID. The Tenant Identifier isn't sent in the token request, so putting the instance scope there won't work. **Wrong region or environment.** Match the Region selection to your BlackLine subdomain (`us`, `eu`, `apac`), and use the Sandbox checkbox only for sandbox instances. **Scope names rejected.** Some scope names are dynamic per instance. If the standard scopes fail, confirm the exact scope names with BlackLine support. `bl.users` and `bl.mdm` plus your instance scope are always required for Lumos. **Provisioning actions fail.** Confirm the connecting user is an admin with API Access enabled. All user lifecycle actions run under that user's permissions.