Frequently Asked Questions
Learn the answers to commonly asked questions, recommended patterns, and best practices for the SKY API.
How do I get started?
Do you have any code samples?
I am seeing an issue, where can I get support?
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:
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
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
authorizationrequest 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 Implicit Flow.
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 Implicit Flow.
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://oauth2.sky.blackbaud.com/authorization Authorization endpoint. 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.
When I register my app, 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 (
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 app 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.
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.
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
DELETE methods, and allow
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 60 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 app, associated with your app'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 app'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.
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 your profile.
Important! Subscription keys are associated with your developer account, and should NOT be shared with the public since it would allow someone else to impersonate you when calling the SKY API!
How do I register my application and get an OAuth 2.0 ID and secret?
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 your application can access their data. An administrator within the customer's organization must first activate your app before any user will be able to use it, and at any time the administrator can deactivate or completely remove your application (deactivating is intended to reflect a short-term state where eventual re-activation is expected). If that happens, your application will not be able to obtain or refresh any access tokens to use when calling the API.
If your application is deactivated or removed, users will see the following message in the authorization process:
“This application has not been approved by your administrator…”
What scopes do you support and how do I pass them in my authorization request?
OAuth 2.0 Scopes are not yet supported within the 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 is limited to the user's security permissions.