Info |
---|
...
title | Summary |
---|
API Keys grant access to LearningBuilder's APIs. They provide both authentication (which member is associated with the API call) and authorization (what APIs is that member allowed to access). |
Index
- 418840629
- Authorization Rule Sets
- API Key Permissions (built-in)
- API Key Permissions (custom)
- Self-Serve API Key management
- Using keys to call APIs
...
API Keys:
...
Table of Contents |
---|
Overview
API Keys provide access to LearningBuilder APIs and services.
API Keys in LearningBuilder:
Are linked to a specific Member record which is the "identity" associated with API requests
Are associated with specific permissions; not all API Keys can call all APIs
Require the associated Member to have an active, granted Member Role in a specified Role list - if the Role is revoked or expires, the API access automatically terminates as well
Can be revoked and reissued from a Member's My Account page, allowing for self-service without administrative intervention
Can be used to secure custom endpoints in the
...
Integration Hub as well
...
API Authorization Rule Sets
Each API Key belongs to an Authorization Rule Set
...
, which are managed in Sys Admin → App Configuration → Authorization Rules.
The API Key itself identifies a user. The Rule Set it belongs to identifies what that key is allowed to do
...
.
Additionally, Rule Sets identify a required Role that the API Key owner must have in order to use the key.
...
Defining the authorization rules in this way means that:
API access can be dependent upon the owning Member's status in LearningBuilder, such that if the owning Member loses an API Key's "Required Role", they automatically lose access to the API as well without requiring any additional administrative intervention.
End users can revoke their API Keys and request new ones through the "self-service portal" in the My Account area, without any risk that end users could abuse the system to gain elevated API privileges.
Rule Set properties
...
Property | Description |
---|---|
Notification Email | (optional - not used by all APIs) Some APIs will generate notifications in response to different conditions, such as when a request cannot be processed because it would violate a business rule. Those APIs will deliver those notifications to this email address. |
Required Roles | (optional - if not specified, no restrictions are enforced) A multi-valued list of Roles. If specified, an API Key will only be considered valid if it is linked to a Member that has a granted Member Role for at least one of these Roles. |
Permissions | One or more permission names that the keys in this Rule Set are allowed to perform. This list can include built-in API Key Permissions for calling standard APIs as well as custom permission names for securing OData endpoints or client-specific APIs implemented via the |
...
API Key permissions
Rule Sets specify the permissions that an API key is associated with.
Name | Purpose |
---|---|
| Allows access to the API/ |
...
Member/DemographicSync API that triggers the Demographic Synchronization process for a specific Member | |
| Allows access to the API/WorkflowInstance/ExecuteImportStep API. |
| Allows access to the API/ |
...
LearningPlanInstance/GetCompetencyAreasWithProficiencies API that returns Competency Classification data about a specific Learning Plan Instance | |
| Allows retrieval of Member data via the legacy (1st generation, non-customizable) OData endpoint. |
| Allows access to the API/ActivityInstance/GetOrCreate API that returns a pointer to an existing Activity Instance, or creates a new one if necessary |
| Allows access to the API/LearningPlanInstance/GetOrCreate API that returns a pointer to an existing Learning Plan Instance, or creates a new one if necessary |
| TODO |
| Allows access to the API/ |
...
WorkflowInstance/PerformStep API that updates attribute data for an existing Workflow Instance and performs a specific Workflow Action | |
| Allows access to the API/ |
...
Member/UpdateMemberRoleUniqueId API that can be used to update the Unique Id associated with a specific Member Role | |
| Allows access to the xAPI endpoint for interacting with LearningBuilder using xAPI-formatted payloads. |
...
Custom API Key Permissions
...
In addition to the built-in API Key permissions, Rule Sets can also define custom permission names.
These custom permission names can be used in conjunction with:
OData endpoints that expose custom-specific database views
Custom API endpoints implemented in the
...
Self-Serve API Key Management
API Keys are designed so that end users can revoke existing keys and request new keys without administrative assistance.
The "API Keys" menu item will automatically appear in the My Account area for any user that already has at least 1 API Key, or has the necessary Role to request a new API Key in one or more Authorization Rule Sets.
If API Keys are not used, and Authorization Rule Sets are therefore not set up, then the link is suppressed to simplify the UI.
To enable administrative users to manage API Keys on behalf of end users via the Admin → Profile Details page, grant the relevant administrative roles the "ManageMemberApiKeys" permission.
...
Using API Keys when making API calls
See Use API Keys to authenticate API calls
...
Requirements
- LearningBuilder 9.1 or later
Implementation Checklist
...
Related articles
Filter by label (Content by label) | ||
---|---|---|
|
...
hidden | true |
---|
...