Skip to main content

Authorization

Follow this guide to create a new Blackboard LMS credential that will allow Nexla to authenticate to and exchange data with your Blackboard Learn instance.
blackboard_api_auth.png

Blackboard LMS

Prerequisites​

The Blackboard Learn connector authenticates using the OAuth 2.0 client credentials (2-legged) flow defined by the Learn REST API framework. Each registered application is assigned an Application Key and Application Secret on the Anthology (Blackboard) Developer Portal, and a Learn administrator must explicitly enable the application on the institution's Learn instance before the API will issue access tokens. Tokens returned by the /learn/api/public/v1/oauth2/token endpoint are bearer tokens valid for one hour, and Nexla automatically refreshes them as needed.

Three pieces of information are required to create the credential:

  • Learn Instance Base URL — the full URL of your Blackboard Learn instance (for example, https://yourinstitution.blackboard.com).

  • Application Key — the OAuth2 client ID issued when the application is registered on the Developer Portal.

  • Application Secret — the OAuth2 client secret issued at registration time. The secret is shown only at registration and cannot be retrieved later.

Register the Application on the Developer Portal​

The Anthology (Blackboard) Developer Portal is the system of record for REST applications. A developer creates one or more applications there, and each application receives the credentials Nexla will use.

  1. Sign in to the Anthology Developer Portal at https://developer.blackboard.com/. If you do not yet have a developer account, complete the registration process before continuing.

  2. From the portal navigation, open My applications, and click the + (Register your application) button.

  3. Select Manual registration, and complete the application registration form with the following details:

    • Application name: Enter a descriptive name (for example, "Nexla Integration").

    • Description: Briefly describe the integration purpose so Learn administrators can identify it during approval.

    • Domain: Enter your organization's domain.

    • Group: Select the appropriate group for the application.

  4. Click Register application to create the registration.

  5. On the application detail screen, copy the following values and store them securely:

    • Application ID — required by the Learn administrator to enable the application on the Learn instance (not entered into Nexla).

    • Application Key — the OAuth2 client ID entered into Nexla.

    • Application Secret — the OAuth2 client secret entered into Nexla. This value is displayed only at registration time; if it is lost, a new secret must be generated.

    For complete details on the Developer Portal and application registration, see the Anthology Developer Docs — First Steps with Learn REST API.

Enable the Application on the Learn Instance​

By default, no REST application has access to a Learn instance. A Learn administrator must explicitly approve the registered application's Application ID before token requests will succeed.

  1. Sign in to the target Blackboard Learn instance as an administrator.

  2. From the Administrator panel, under Integrations, select REST API integrations.

  3. Click Create integration.

  4. In the Application ID field, enter the Application ID copied from the Developer Portal registration.

  5. In the Learn User field, select the Learn user account that the integration will run as. The application's API calls execute with this user's effective permissions, so the user must have the entitlements required by the endpoints in scope (for example, course read, gradebook write, user provisioning).

  6. Set End User Access and Authorized To Act As User according to your institutional policy:

    • End User Access: Set to Yes to allow three-legged user-context calls. For the Nexla client-credentials flow, this can typically be left at the default.

    • Authorized To Act As User: Set to Yes only if the integration should be allowed to impersonate other users; leave at No otherwise.

  7. Click Submit to save the integration. The application is now permitted to obtain tokens against this Learn instance.

    The Learn user that the integration runs as governs what data the connector can read or write. Use a service-account user with the minimum entitlements required, rather than a personal account.

Important

The Application Secret grants access to your Blackboard Learn instance via the registered application. Store it in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed. Tokens issued by Learn are short-lived (one hour), but the secret itself does not expire until it is regenerated.

For complete information about the Learn REST API authentication framework, see the Anthology Developer Docs — REST API Framework and Basic Authentication with REST.

Create a Blackboard LMS Credential​

  • To create a new Blackboard LMS credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Authentication Settings​

  1. Enter the full URL of your Blackboard Learn instance in the Learn Instance Base URL field (for example, https://yourinstitution.blackboard.com). This value is used as the base URL for all Learn REST API calls and for the OAuth2 token endpoint at <base-url>/learn/api/public/v1/oauth2/token. Do not include a trailing slash.

  2. Enter the Application Key issued for your registered Blackboard application in the Application Key (Client ID) field. This value acts as the OAuth2 client_id and is obtained from the application detail screen on the Anthology Developer Portal.

  3. Enter the Application Secret issued for your registered Blackboard application in the Application Secret (Client Secret) field. This value acts as the OAuth2 client_secret and is treated as a password — the field is masked on entry.

    Nexla exchanges the Application Key and Application Secret for an access token by calling POST <base-url>/learn/api/public/v1/oauth2/token with grant_type=client_credentials. The returned bearer token is automatically applied to subsequent Learn REST API calls and refreshed on expiry.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential. Nexla will issue a test token request against the Learn instance to verify that the application is registered, enabled on the instance, and that the supplied key and secret are correct.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.