How do I get started?

The Getting Started guide and Authorization Code Flow tutorial demonstrate basic implementations of SKY API using easy-to-follow setup instructions.

Do you have any code samples?

See Code Samples. Our Endpoint Reference contains code samples in multiple languages.

I am seeing an issue, where can I get support?

See our Issues page for any existing issues. If you find a new issue, please contact us.

How do I pass security credentials from my application to the SKY API?

To call the SKY API, your application will need to provide two things:

1. Your developer subscription key - this key represents Blackbaud's permission for you to call the API, and it should be sent as part of the Bb-Api-Subscription-Key request header.

2. An access token - this represents a Blackbaud customer's permission for you to access their data, and it should be sent as part of the authorization request header. This token is associated with the authenticated user's account and organization, and can only be used to access data to which the user has permission.

For more information, see request headers.

What is the recommended authorization flow for a browser-based app?

In applications where you cannot maintain the confidentiality of their Application secret, the most appropriate OAuth flow to use in this case is the Authorization Code Flow with PKCE.

Browser-based (JavaScript) apps run entirely in the browser after loading the source code from a web page. Since the entire source code is available to the browser, they cannot maintain the confidentiality of their Application secret, so the secret is not used in this case.

See Authorization to learn about the OAuth flows that are supported.

What is the recommended authorization flow for a native applications?

Like browser-based apps, the most appropriate flow to use for a native applications (desktop and mobile devices) is the Authorization Code Flow with PKCE.

See Authorization to learn about the OAuth flows that are supported.

I want to create a script that adds new constituents to my database every day. Is there a way I can do this without having to open the browser and log in? (My username and password would preferably be set in the script.)

The SKY API doesn’t support basic authorization through username/password. Instead, obtain an access token through the Authorization Code Flow.

When should my application initiate authorization?

Authorization begins when your application redirects the user's browser to our https://app.blackbaud.com/oauth/authorize Authorization page. Exactly when you decide to make this request is up to you. You can request authorization when your application gathers initial information from the user, or when the user first attempts to access some data from the SKY API.

See Authorization.

When I register my application, can I use localhost in my redirect URIs?

Yes. We allow you to register multiple redirect URIs with your application. For production, we require https, but to facilitate local development we allow http and the use of localhost or the localhost IP (127.0.0.1).

See Register your application and the Auth Code Flow tutorial.

After redirection occurs, how can I track where authorization initiated?

After the user grants (or denies) access to your application, we'll redirect the browser to the URI that you passed to us when you initiated the authorization process (this URI must exactly match one of the values you registered with your application).

We also support the OAuth 2.0 state parameter (described in Section 4.1.1 of the OAuth 2.0 spec), which allows you to provide some context to us that we will echo back to your redirect URI after the user grants (or denies) access to your application. We recommend that you use an opaque value and verify that it matches the value you provided when your application initiated authorization. In this way, you can prevent cross-site request forgeries as well as track where your application initiated the authorization flow. You can then further redirect the user's browser to the appropriate area within your application upon consent.

See Authorization.

When must my application re-authenticate the user?

If both your access token and refresh token have expired, then you'll need to send the user back through the interactive authorization process. If your access token has expired but you have a valid refresh token, then you can simply exchange the refresh token for a new access token (and a new refresh token) non-interactively.

See Authorization.

Do you support cross-origin resource sharing to allow you to interact securely with our API from within the browser?

Yes, we've enabled CORS support in the SKY API. We allow all origins (*), support the GET, PUT, POST, PATCH, and DELETE methods, and allow Bb-Api-Subscription-Key, authorization, accept, and content-type request headers.

When do my tokens expire?

During the initial user-interactive authorization process, the authorization code sent to your application will expire in 5 minutes, which means you have a very short window of time in which to exchange the authorization code for an access token.

Access tokens will expire in 60 minutes, after which you can use the refresh token to obtain a new access token (and a new refresh token). For the Authorization Code Flow, refreshing an access token does not involve any user interaction, so your application can have indefinite connectivity to the SKY API once the user provides consent.

Refresh tokens are longer-lived values that will eventually expire in 365 days, using a sliding window model. As long as your application connects at least once to the SKY API within the window, it will be able to retain connectivity to the customer's data.

See Token Expiration.

May I store access tokens in my application's database?

Yes, you may store access tokens and refresh tokens within your application, associated with your application's concept of a user (if applicable). When the user logs in with your application's credentials, you can check to see if you have an access token for that user and adjust your application's experience accordingly. For example, you may immediately route the user through the authorization process in order to obtain an access token, or disable functionality until the user provides consent.

If your application doesn't have the notion of user credentials, you can simply direct the user to log in with their Blackbaud credentials when they log into your application. We'll provide you with the user's access token and expiration details as part of the Token response during the authorization code flow.

In any case, be sure to store access tokens and refresh tokens securely in your system so that they aren't exposed to the public.

What is the purpose of the subscription key?

The subscription key is associated with your developer account and must be provided as part of the Bb-Api-Subscription-Key header when calling the SKY API. It represents our permission for you to call the API, and we also use it to enforce usage limits (see Rate limits and Quotas) to ensure that the API performs well for everyone. We also aggregate API call analytics associated with your subscription to show you how your apps are performing within the Analytics area of the portal.

See Subscription.

Why do I have two subscription keys?

When you obtain a subscription to the SKY API, we'll provide two keys (primary and secondary) that you can use when calling the API. Both keys are equally functional; we provide two keys to support rotation on your end.

We don't require you to rotate your subscription keys, and you can adopt whatever key rotation schedule and strategy that best fits your needs. If you do need to regenerate your subscription keys, you can do so from the My subscriptions page.

How do I register my application and get an OAuth 2.0 ID and secret?

You can register your application in the My Applications area to obtain the unique ID and secret, which will be used during the authorization process to obtain an access token to call the API.

See Managing your apps.

My application secret may have been compromised, what should I do?

If you believe your application's secret has been exposed, you should regenerate the secret and update your application to use the new value when calling the SKY API.

What control does a Blackbaud customer have over my application?

Customers always have control over whether or not an application can access their data. An administrator within the customer's organization must first enable your application before any user will be able to use it, and at any time the administrator can remove your application. If that happens, the application will not be able to obtain or refresh any access tokens to use when calling the API.

If your application is removed, users will see the following message in the authorization process:

See Authorization.