Blackbaud SKY API Authorization

Blackbaud SKY API uses OAuth 2.0 to authorize API requests (official documentation). Practically, this means that before you can use any of the Civis Platform script templates that interact with Blackbaud SKY API, you need to have created and configured a Blackbaud developer account, as well as set up certain Civis Platform custom credentials. The following are the steps to set up Blackbaud SKY API authorization. Note, these steps have to be executed only once for a given Civis Platform user account with the exception that your Blackbaud refresh token may expire (365 days after creation) and will need to be regenerated from time to time.

After the following steps are completed, you should have:

• A Blackbaud developer account with an application created and configured for Civis Platform
• A Civis Platform custom credential for your Blackbaud “application”
• A Civis Platform custom credential for your Blackbaud refresh token
• A Civis Platform custom credential for your Blackbaud “subscription”

Steps

• Log on to your Blackbaud developer account, or create one if you don’t have one already.
• Once logged in, click “My applications” on the developer account sidebar. If you don’t already have an application, create one and name it “Civis data” or something similar.
• When the application is created, an Application ID (OAuth client_id) and a Primary application secret (OAuth client_secret) are generated. These will be used to create a custom credential on Civis Platform in the next step.
• Go to Civis Platform and create a new credential with the following:
  • Type “Custom”. 
  • Username is the Application ID (OAuth client_id) from Blackbaud.
  • Password is the Primary application secret (OAuth client_secret) from Blackbaud.
  • For description, name it so that it says “application ID” to differentiate it from other Blackbaud credentials you’re going to create below.
• Use the Blackbaud OAuth Deployment Script to deploy an OAuth Service application that will be used for authorization.
  • Blackbaud Application ID and Secret (required): The Blackbaud client custom credential.
• If the deployment script runs successfully, you should see the URL for the Service and Report in the logs and Run Output.
• In a new tab of your web browser, go to the Service URL, where a Civis Platform service should be deploying. Once the deployment is complete (deployment takes up to 10 minutes; you should see “Application successfully changed to ready state” in the last line of the logs), scroll down the page and click the “Advanced” dropdown. Copy the URL that is under the “Current” section. The URL should look like this:
  “https://services--12345676-civis.shiny-1.services.civis.io”
• In your Blackbaud developer account, go to the application you’ve created, scroll down the page, and you should see a section marked “Settings”. In the application settings find the dropdown for “Redirect URIs”, and add the Civis Platform service URL from the previous step.
• In the same application settings section, find the dropdown for “Scopes”, specify the level of data access by selecting at least the “Limited data access” option and also select the “Read” checkbox under “Raiser’s Edge NXT”. This enables the application to access the data that the consenting user can see.
• Go back to the web browser tab with the deployed Civis Platform service. Click “View Report” from the service page to run the report and complete the Blackbaud authorization flow. (You may have to allow pop-ups for your web browser.) Once this step is completed, you should have a new Civis Platform custom credential for your Blackbaud refresh token. (Note that your Blackbaud refresh token may expire (365 days after creation) and will eventually need to be regenerated. If this happens, simply go to this same deployed Civis Platform service report and complete the Blackbaud authorization flow again. After that, the same Civis Platform custom credential will be overwritten with a new Blackbaud refresh token.
• Now we need to create another custom credential on Platform for subscription ID (needed for the actual import template, not for the service app that generates the refresh token). In your Blackbaud developer account interface, go to “My subscriptions”. You should see different subscription options.
• Select “Subscribe” under the “Standard APIs” option, review all the terms by scrolling down the page before you can agree to the terms and submit.
• You can then locate your subscription details on the subscriptions page. The Standard APIs subscription key enables us to make calls to a standard group of Blackbaud SKY API endpoints.
• Go to Civis Platform and create a new credential with the following:
  • Type “Custom”. 
  • Name can be “Blackbaud subscription ID” or something similar (no exact name requirement).
  • Username doesn’t matter – it can be your email address.
  • Password is the “Primary access key” from your Blackbaud’s “My subscriptions” interface.