Authorization

SKY API uses the OAuth 2.0 protocol to authorize API requests. This provides a mechanism for your application to access Blackbaud customer data without exposing any user credentials (username/password) to your application. Instead, users must provide consent to your application to access data on their behalf.

SKY API OAuth 2.0 endpoints:

Endpoint URL
Authorization https://oauth2.sky.blackbaud.com/authorization
Token https://oauth2.sky.blackbaud.com/token

In order to call the SKY API, you must first register your application within the My Applications area of the developer portal. This registration provides your application with a unique set of credentials to use when asking a user for consent.

Before your application can access a given Blackbaud customer's data, it must first be approved by an administrator within the customer's organization. The administrator provides this approval by activating your application within the Applications area of the product. This allows Blackbaud customers to control which applications have access to their data, and at any time an administrator can de-activate your application and prevent future access via the API.

Once your application has been activated, you can then obtain consent from an authenticated Blackbaud user. Upon consent, an OAuth 2.0 access token will be issued to your application in the form of a JSON web token, or JWT. The token should be included on every API request as part of the standard Authorization header. It is tied to the authenticated user's account and organization, which means that your application can only access data to which the authenticated user can access within the system.

Supported OAuth 2.0 flows

The SKY API supports the following grant types:

  • Authorization Code Flow (aka the Web Server flow). This flow is meant for web applications where API calls are made from the server. It is the most secure as it involves server-to-server communication, and is also the most functional as it also provides refresh tokens. This allows your application to have indefinite connectivity to the SKY API after the one-time user-interactive consent process.

  • Implicit Flow. This flow is meant for client-side applications, such as browser-based, native, and mobile applications. Since API calls are made from the client, they are inherently less secure and do not involve the exchange of an application secret. The access tokens that are issued are short-lived and no refresh tokens are provided, so the user must re-authorize your application when the token expires.

User experience

The Authorization Code Flow starts by redirecting the user's browser from your application to our Authorization URL. The user will login (using their Blackbaud or Google credentials), confirm that it's OK for your application to access their data, and then we'll redirect back to you with a authorization code that you can exchange for an access token. You can store this access token (and the refresh token) in your application, and use it when making API calls on that user's behalf.

The Implicit Flow starts by redirecting the user's browser from your application to our Authorization URL. The user will login (using their Blackbaud or Google credentials), confirm that it's OK for your application to access their data, and then we'll redirect back to you with an access token that you can use when making API calls on that user's behalf.

Token expiration

As a security best-practice, access tokens will expire after a period of time (currently, 60 minutes). When this happens, your application should exchange the refresh token it received with the original access token for a new access token in order to make additional API calls. The refresh token exchange happens on the server and does not involve any interaction with the user.

If your access token was obtained using the Implicit Flow, you won't have a refresh token and you'll need the user to re-authorize your application before making additional API calls.

Note: Refresh tokens will also expire, but after a much longer period of time (currently, 60 days). Using a sliding window, each time you exchange your refresh token for a new access token, we will issue a new refresh token as well. As long as your application connects to the SKY API at least once within the window, you will be able to continue accessing the Blackbaud customer's data indefinitely (or until they deactivate your application).

Scopes

OAuth 2.0 Scopes are not yet supported within SKY API - in the future, applications may be able to express intent via scopes but for now API access is always within the context of an authenticated user, which means that API access respects the user's security permissions defined within the product.