How To Authorize Users For Headless Apps

Our team was recently asked to clarify our recommendation on how to get and maintain authorization to SKY API for apps that offer no user interface, such as apps that perform sync operations to and from Blackbaud products. This blog post addresses the confusion around this and describes the basics for establishing a long-lasting SKY API connection that doesn't involve recurring user authorization.

User Context
SKY API supports the OAuth 2.0 protocol to authorize API requests. Specifically, it supports the Implicit and Authorization Code grant types. Both of these flows require a user to give consent to an app through the SKY API consent form that authorizes the /authorization OAuth 2.0 endpoint. This means SKY API requires a UI where the user can provide consent. Before we consider what the UI requirement means for your app, let's take a closer look at the user.

All valid SKY API requests are made in the context of a Blackbaud user, which today includes Raiser's Edge NXT and/or Financial Edge NXT users. To access product data via SKY API, your app requires consent from an authenticated user. Your app makes requests on behalf of that user, so it is limited by the user's permissions. A supervisor with all rights can authorize your app, but so can a very limited-rights user. When you engage with Blackbaud clients, we recommend that you work with them to create a user account with only the permissions that your app requires for sync operations and API requests.

For example, if your app synchronizes data to and from Raiser's Edge NXT exclusively through the Constituent API, then clients can create a security group in Raiser's Edge NXT Database View that only has access to perform the necessary Constituent-level record operations. If necessary, clients can grant additional permissions in Raiser's Edge NXT Web View. Then clients can create a Raiser's Edge NXT user account specifically for this security group and use it to provide consent to your app through the SKY API OAuth consent form.


Clients can create a security group in Raiser's Edge NXT Database View.


Then clients can add a Raiser's Edge NXT user to the security group.


If necessary, clients can grant additional permissions to the security group in Raiser's Edge NXT Web View.

Authorization Code Grant Type
As I mentioned before, SKY API supports two OAuth 2.0 grant types: Implicit and Authorization Code. To perform API operations without recurring user authorization, your app must use the Authorization Code Flow. The SKY API documentation site provides an overview and step-by-step instructions for this grant type. This grant type provides your app with a refresh token that can be used to generate a fresh access token after the previous access token expires.

We receive a fair amount of questions about access tokens and when to use refresh tokens. The access token is the authorization context that your app uses to make SKY API requests, and it expires after 60 minutes. If your app continues making API requests with the expired access token, you will receive 401 Unauthorized errors. The app can use the refresh token to generate a new access token and continue making successful API calls.

It is not necessary to preemptively use the refresh token before the access token expires. A refresh token is good for 2 months, or until the app uses it or the Blackbaud client revokes it. So you can generate a new access token with a valid refresh token long after the original access token expires.

For example, if your app performs a sync operation once a week for half an hour, then it needs to use a refresh token to generate an access token once a week at the start of the operation. And if a weekly sync operation runs for several hours, then your app needs to use a refresh token to generate an access token at the start of the operation and again every 60 minutes when the previous access token expires. Your app does not need to refresh access tokens throughout the week when it isn't making API requests.

User Authorization
The main question we receive about apps that perform sync operations is whether they need to provide a UI for the user to provide OAuth consent to an app. That user must visit the SKY API OAuth consent form to authorize your app to perform SKY API requests. After the user provides consent, we send the user to a redirect URI that you specify when you register your app.

So, if you create an app for consumers other than yourself or your organization, your app almost certainly needs to provide a user interface to at least handle the Authorization Code Flow redirect. Fortunately, unless the refresh token expires or the Blackbaud client revokes it, the user may never see this UI again. You can use the interface to establish trust with the user and to introduce the user to your app's features. Alternatively, you can build a page to handle the Authorization Code Flow redirect; you would simply email your client a URL for the SKY API consent form that includes parameters to provide authorization to your app. To get started with the Authorization Code Flow development, check out our code samples.

Local Development and Trusted Apps
If you create a backend integration for your organization, or if you just need access tokens and refresh tokens to use during development, tools are available to lead you through the Authorization Code Flow without building a UI. SKY API follows the OAuth 2.0 specification, so you can use any tool that can be used to authorize against that spec. I will demonstrate this with a tool I've blogged about before: Postman.

To get an access token and refresh token for your app from Postman, add “https://www.getpostman.com/oauth2/callback” as a redirect URI on your app. You can read more about creating and maintaining your app. Before you open Postman, take note of your app's client ID and Secret.

You can use the following steps to create an access token in Postman. And you can review the Postman documentation for more information.


Postman

1. Open Postman.
2. Create a request.
3. On the new request's Authorization tab, change the authorization type to OAuth 2.0.
4. Click Get New Access Token. The Get New Access Token dialog appears.

The Get New Access Token dialog

1. On the Get New Access Token dialog, enter the SKY API authorization and token URLs.
2. Enter your app's credentials.
3. Select “Authorization Code” as the grant type.
4. Click Request Token.

From here, you'll be guided through the Authorization Code Flow, including the SKY API consent form. After you consent, Postman displays the /token response contents.


The SKY API access token response in Postman

You can copy the access_token and refresh_token values into your app's key storing mechanism. Make sure to do this in a safe fashion so your access token is not compromised.

Other Considerations
As I mentioned before, refresh tokens can expire or be revoked. After an access token expires, your app can use a refresh token to generate a new access token. However, if your refresh token is no longer valid, your app will receive an error response. Your app needs to handle this scenario. If your app is for you or your organization, you probably should alert yourself through some mechanism that your app needs to be reauthorized. If your app is for other consumers, you may want to disable the sync for that client.