Attention! Use tokens for ON API by June 30
We have an important announcement to share regarding Higher Education schools using the legacy ON API and an action that must be taken before June 30, 2021.
Applications and integrations which rely on “legacy” ON API endpoints must use the new authentication tokens (Key and Secret), instead of “legacy” usernames and passwords.
- Users with the ON API Access Manager role should go to Core, Security, Authentication settings, ON API Access. Then follow the instructions in the online help to generate authentication tokens (Key and Secret) for user accounts used by “legacy” ON API application and integrations. A platform manager can grant the ON API Access Manager role to themselves or to another user at your school.
- Please join us in the discussion thread in the User Community. A technical writer is actively monitoring the thread for any questions that need responses. You can also discuss APIs with your peers there.
- For developers, we’ve updated the ON API site to include basic instructions for generating authentication tokens, managing security roles, and using the POST method of authentication.
OverviewWe continue to support both of our REST APIs. The REST APIs enable two applications to talk to each other, such as Blackbaud Education Edge and Connect Raiser’s Edge, a third party partner integration, or a custom app for your school.
The two supported REST APIs are the newer SKY API and the “legacy” ON API.
SKY APIWe recommend new development use the newer SKY API instead of the “legacy” ON API.
The SKY API has parity with the “legacy” ON API and is being expanded with new development.
SKY API is a REST API.
“Legacy” ON APIThe “legacy” ON API is no longer being expanded. As we update Blackbaud Education Edge with new features, endpoints won’t be added to this “legacy” ON API. Thus, we discourage new development from using the “legacy” ON API, even though we continue to support the “legacy” ON API for older integrations and applications.
To continue using the “legacy” ON API, you must update to use authentication tokens (generated in Core) by June 30, 2021.
Additionally, if users log into a “legacy” ON API app you built with their “legacy” username and password, you will need to switch to SKY API and Blackbaud ID to maintain that kind of authentication to limit the data the user can access. However, if you don’t need to limit the data and users don’t login, you can remain on the “legacy” ON API.
The “legacy” ON API is a REST API.
SOAP APIWe no longer support SOAP API, which is a different type of API from REST APIs. Any applications or integrations based on SOAP API should be migrated to newer SKY API (which is the REST API we recommend for all new development).
Who is affected?If your school had someone develop your own applications or integrations using ON API, then you are affected and must act by June 30.
If a platform manager grants someone the ON API Access Manager role and that manager sees any user accounts listed in Core > Security > Authentication settings > ON API Access then you’re affected and must act by June 30.
If your school uses an application by an affected partner, then you’re affected and must act by June 30. Blackbaud has been in contact with many of these partners so they can prepare for the change. Some information about their preparation, preferred contact methods for specific partners, and more is in this KB article from Blackbaud Customer Support.
- Connect Raiser’s Edge (RE)
- Industry Weapon
- Studyo / Intuitic
If you use a “sandbox” for your “legacy” ON API applications and integrations, your sandbox environments will also be affected. Complete the action for the “sandbox” environment first. Then repeat the actions for your live instance of Blackbaud Education Management.
Security rolesThe process for granting the ON API Access Manager role is the same as the process for granting any other roles.
- The platform manager should log into Blackbaud Education Management.
- Use the People Finder to open the user's Core profile.
- Go to the Access tab.
- Select to edit the user's Role Membership.
- Enable the ON API Access Manager Role for the user.
- The user with the ON API Access Manager role can then login and set up authentication tokens (Key and Secret).
Generate tokens (Key and Secret)Users with the ON API Access Manager role should use the ON API Access task to view a list of users' accounts who are currently (or were previously) able use "legacy” ON API endpoints to access your data.
- The ON API Access Manager should log into Blackbaud Education Management.
- Go to Core.
- Select Security.
- Select Authentication settings.
- Select ON API Access. (Troubleshooting tip: If you don’t see this tab, update your security roles.)
- Generate an authentication token for each user account on the list that should maintain access. The token includes both a Key and a Secret. For security purposes, this information will not be visible after you save and return to the list. Copy this information and save it to a secure location. If you lose this information, you’ll need to regenerate tokens with new information.
- Contact each active developer or and provide them with their Key and Secret for their authentication token. Or provide the token information to the application.
- Update the user accounts’ roles to ensure they have the relevant security roles that grant them access to the necessary endpoints.
- Make the keys for user accounts Active to enable the user account to access your data with "legacy" ON API endpoints.
Be aware that authentication tokens (Key and Secret) periodically expire and must be regenerated. For more details, see the online help.
Update applications and integrations
Developers and managers must update their application's configuration setup to use the authentication token (Key and Secret) before June 30, 2021. Until then, both the legacy and new token authentication methods will work.
Developers can either:
- update their POST method
- or use the user interface (UI) of their application to update their app's setup.
Instructions are also available on the ON API site for developers.
For example, the integration manager or Connect Raiser’s Edge manager can log into Raiser’s Edge (RE) and edit the Settings (gear icon) for the Connect Raiser’s Edge plug-in. Replace the “legacy” information with the newly generated token information. The Connect Raiser’s Edge plug-in is an example of how you can use the user interface (UI) of an application to update the app's setup and thus avoid making a code change.
Take noteLiterally. Write it down.
Consider updating your school’s Policies and Procedures guide to indicate:
- which integrations correspond to each user account,
- which member of your staff is responsible for each account (especially if the application’s “user” account is different from the staff’s primary account),
- any tokens (keys and secrets) if this is a secure guide to store them in,
- contact information for any third-party partners or vendors,
- locations and purposes for any “sandbox” environments,
- and any other information your school finds useful relating to custom applications, integrations, partners, and vendors.