Scopes

Application scopes operate at Blackbaud following the principle of least privilege. Putting the security of our customers as our top priority, this concept ensures that apps only have access rights to what is required to do its job and nothing more. In addition to your application only being able to access data that a consenting user can access, we also introduced scopes so that you can proactively define only the data access that your application needs in a Blackbaud customer environment. This information is also visible to admins when they review your application in the Blackbaud Marketplace, so that they can make more informed decisions about what apps are a good fit for their mission. 

To protect you and our customers, we ask you to define scopes for only the permissions you need for your application. When you add new functionality to your application, you can re-define your scopes and get approval for the new data access from the Blackbaud environment’s admin.

Full data access – When this option is selected, your application can operate in the context of the consenting user's permissions across all solutions, including future solutions, in the environment. If you add additional functionality, it does not require admin approval. Your access is only constrained by what the consenting user can do.

Limited data access – When this option is selected, specify the level of access you need per Blackbaud solution. The options include:

  • Read – enables your application to see data the consenting user can see, but not make any changes.

  • Write – enables your application to see and change data that the consenting user can change, but not delete.

  • Delete – enables your application to see, change, and delete data that the consenting user can change.

  • Subscribe to events – enables your application to receive event notifications via webhooks when data changes in the application, but not change or delete anything.

Note: Just because an application requests a certain level of access, if the consenting user doesn't have that permission, your application won't be able to perform that action. For example, a volunteer in a Blackbaud solution has rights to enter gifts, but not delete. If your application requests access to read, write, and delete data but the volunteer authorizes your app, the application will not be able to perform any delete actions because the volunteer cannot.

No data access – If your application doesn’t require any access to the customer’s Blackbaud environment data, select this option. For example, you can provide a service outside of Blackbaud solutions or use SKY Add-ins that don’t require SKY API access.

When you change your application's data access by defining new scopes, the changes don’t take effect until an admin for the Blackbaud customer reviews and approves the change. Until they approve, your application operates with the scopes previously approved.

In general, the scopes can be mapped to the following HTTP verbs as seen in the REST API, with a few exceptions, such as the Webhook API.

Scope HTTP verb/API

Read

GET

Write

POST, PATCH, PUT

Delete

DELETE

Subscribe to events

Enables webhook subscriptions to be created and managed

SKY API uses the OAuth 2.0 protocol for authorizing API calls to be made to a customer environment. The authorization flow involves an interface that enables an authenticated Blackbaud ID user to give your application consent to call SKY API in their Blackbaud environment. When your application is authorized, it is operating under the consenting user's permissions.

  • Whatever the consenting user can do, your application can also do via SKY API.

  • Whatever the consenting user cannot do, your application also cannot do via SKY API.

However, your application may not need to do everything the consenting user has permission to do. That’s why you define the scopes of what data access your application needs to perform its functions. By defining only what you need, it’s more secure for you and for Blackbaud customers.