Attention! Use tokens for ON API by June 30
Published
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.
As we mentioned in a previous What’s New letter, schools must act by June 30, 2021 to keep any applications or integrations that use the “legacy” ON API running.
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.
The two supported REST APIs are the newer SKY API and 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.
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.
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.
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.
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:
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.
Consider updating your school’s Policies and Procedures guide to indicate:Discuss
Thanks for stopping by the blog this week! We hope you found this information to be informative and helpful especially for those of you still using legacy code. We have another double blog week coming up so make sure to come back on Thursday when we have another special announcement to share with you, especially those who are educators. See you then!
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.
Overview
We 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 API
We 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 API
The “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 API
We 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.
- BoardingWare
- BrightArrow
- CampBrain
- CrisisGo
- Connect Raiser’s Edge (RE)
- EdTech
- Finalsite
- Industry Weapon
- Magnus
- PickATime
- Ravenna
- REACH
- rSchoolToday
- Ruvna
- SchoolAdmin
- SchoolDoc
- SchoolPass
- Studyo / Intuitic
- TextBookHub
- Vidigami
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 roles
The 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 note
Literally. 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.
Discuss
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.
Thanks for stopping by the blog this week! We hope you found this information to be informative and helpful especially for those of you still using legacy code. We have another double blog week coming up so make sure to come back on Thursday when we have another special announcement to share with you, especially those who are educators. See you then!
News
Blackbaud Higher Education Solutions™ Announcements
02/23/2021 9:00am EST
Leave a Comment