ON API Authentication Tokens (Access)

REST APIs enable two applications to talk to each other, such as Education management and Connect Raiser’s Edge, a third party partner integration, or a custom app for your school.

  • SKY API

    • We recommend all new development SKY API for schools instead of the "legacy” ON API.

    • The SKY API has parity with the “legacy” ON API and is being expanded with new development.

    • We support this REST API.

  • "Legacy" ON API

    • The "legacy” ON API is no longer being expanded. As we update Blackbaud Education management 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.

    • 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 and to limit the data the user can access.

    • We support this REST API.

For more general information about APIs, see API & SDK.

Users with the ON API Access Manager should use this to view a list of users' accounts who are currently (or were previously) able use "legacy” ON API endpoints to access your data or who manage integrations.

We recommend using separate user accounts for website login access from the API integration. Consider enabling developers to login to the Education Management user interface with a different user account via Blackbaud ID.

  • If a staff member develops an application, create a separate user account for that purpose instead of using their main account for both app development and logging in to your school site. If the staff member leaves your employment, you can then disable the user account they used to login, while maintaining the developer account to keep the application running.

  • Additionally, using separate accounts makes it easier to troubleshoot defects in applications, since you can use the Login History to review exactly when the app ran. If the staff logged in every day with combined account, instead of separate accounts, you’d be unable to review which logins were for the application compared to the website.

Schools who:

  • have someone develop their own applications,

  • run integrations that use ON API,

  • have user accounts appear in the list for ON API access,

  • use applications by one of the third party partners mention in this Blackbaud Support KnowledgeBase article,

  • use different third-party partner or vendor who has direct access via the SDK,

  • or use a "sandbox" for for your “legacy” ON API applications and integrations,

must use authentication tokens (Keys and Secrets) for ON API. Configure “sandbox” environment first, and then repeat the actions for your live instance of Blackbaud Education Management.

Tip: Tokens are for developers and integration managers who create or maintain the integrations and applications. You don't need tokens for every student, teacher, etc.

You must have the ON API Access Manager role to view this task.

If you don't have an ON API Access Manager, a platform manager should grant this role to themselves or other users who manage APIs and security. See roles. Then the ON API Access Manager can check the list for user accounts.

  1. Go to Core.

  2. Select Security.

  3. Select Authentication settings.

  4. Select ON API Access. The list appears.

Tip: You may need to grant or revoke other roles (such as the Connect Raiser’s Edge Manager role) later, when you generate tokens (Keys and Secrets).

An ON API Access Manager must update the credentials for any user accounts used by “legacy” ON API application and integrations.

  1. Go to Core.

  2. Select Security.

  3. Select Authentication settings.

  4. Select ON API Access. User accounts and their information appear in a list.

  5. Generate an authentication token for each user account on the list that should maintain access. The token includes both a Key and a Secret. Copy this information and save it to a secure location so you can provide it to the application or partner.

    For security purposes, this information will not be visible after you save and return to the list. If you lose your copy, you’ll need to regenerate tokens with new information.

Contact each active developer and provide them with their Key and Secret for their authentication token.

Ensure they know where to enter these credentials in their application’s configuration setup.

Developers instructions are included in the "legacy” ON API site as documentation for "Getting started" and "Basics: Authentication."

  1. Developers should use the POST method with Route: https://{school}.myschoolapp.com/api/authentication/login.

    The body of the POST should contain the following JSON structure:

    {

    "username": "example",

    "password": "example"

    }

  2. Enter the Key in place of “example” for the username. Do not enter an actual username.

  3. Enter the Secret in place of “example” for the password. Do not enter an actual password.

If an application (such as Connect Raiser’s Edge) has a user interface for authentication information:

  • enter the Key in the Username or Key field.

  • enter the Token in the Password or Token field.

For each developer or integration manager's user account, update the user accounts’ roles to ensure they have the relevant security roles that grant them access to the necessary endpoints.

Their current roles are shown in a column. Users without any roles appear as (no roles). Sort or filter the list by this value to quickly find them.

From the list for ON API Access, select a user’s name to go to their user profile. Select the Access tab and edit their Role membership.

Additional roles:

  • Web Services API Manager

  • Magnus Health Manager

  • Vidigami Manager

  • Connect RE Manager

  • REACH Manager

  • School Doc Manager

  • SchoolAdmin

  • Ravenna Manager

  • EdTech Manager

  • Finalsite Manager

An ON API Access Manager must update the credentials for any user accounts used by “legacy” ON API application and integrations.

  • Active - Enables user to use “legacy” ON API endpoints to access your data. You can filter the list to only show active keys.

  • Inactive - The user will no longer be able to use “legacy” ON API endpoints to access your data.

    When you mark a key Inactive, the user account is blocked from accessing the “Legacy” ON API, which breaks the “legacy” application or integration. If you then mark the Inactive key as Active again, and the token hasn’t yet expired, the integration will continue to work.

    You can Delete inactive keys to permanently remove the key and the user account from the list.

Users with Legacy Access as Yes currently log into Blackbaud Education Management with a “legacy” username and password.

If their “legacy” username and password was previously used to authenticate into the ON API or integrations, test the integration using their new authentication token (Key and Secret) before you remove the “legacy” username/password.

After a successful test, you can update these users to login with Blackbaud ID. From ON API Access, select a user’s name to go to their user profile. Select the Access tab and edit their login information to remove the “legacy” username and password.

If a user account doesn’t login with a new token for 90 days, the key and secret expire. You’ll need to generate a new key to replace the expired one. Share the new token with the application or developer.

If a user account is active for the "legacy" ON API within the first 90 days, the token’s expiration date automatically extends for another 90 days. The expiration will continue to extend in this manner, up to 365 days.

Each year, you must generate a new token to replace the expired one. Share the new token with the application.

Tip: Remember to copy the authentication token Key and a Secret. Then save it to a secure location so you can provide it to the application or partner. For security purposes, this information will not be visible after you save and return to the list. If you lose your copy, you’ll need to regenerate tokens with new information.

We recommend schools maintain an internal document that indicates:

  • 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 authentication tokens, including 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.