API Keys
- Seth Petry-Johnson
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).
See also: Use API Keys to authenticate API calls
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
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 Integration Hub. |
API Key permissions
Rule Sets specify the permissions that an API key is associated with.
Name | Purpose |
|---|---|
| Experimental support for Zapier integrations using Polled Data Files |
| Grants access to API/WorkflowImportQueue/CreateBatch |
| Grants access to API/Member/DemographicSync |
| Grants access to API/WorkflowInstance/PerformImportStep |
| Grants access to https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/419168299 |
| Allows retrieval of Member data via the legacy (1st generation, non-customizable) OData endpoint. |
| Grants access to API/ActivityInstance/GetOrCreate |
| Grants access to API/LearningPlanInstance/GetOrCreate |
| Retrieves data about a Workflow Object given its ID. |
| Grants access to API/WorkflowInstance/PerformStep |
| Grants access to |
| Grants access to remotely trigger various diagnostic tests. Internal use only. |
| Grants access to the System Insights feature. Internal use only. |
| Grants access to API/WorkflowInstance/SetAttributeValues |
| Grants access to https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/3683024897. Internal use only. |
| Grants access to https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/418873428 |
| Grants access to the xAPI API endpoints |
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 Integration Hub
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.