Skip to main content

​
After this article

You’ll be able to connect BlackLine to Lumos to sync and provision users, entities, roles, and team memberships.

​
Capabilities

​
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_<InstanceGUID>). 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_<GUID>, 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 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

​
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_<your-instance-GUID> (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.