The SKY API documentation is very good compared to many APIs that I work with. One area that is particularly useful is the “Try It” area where you can test an endpoint with your own data. One small annoyance is that if you want to try a number of different endpoints, you need to go through the whole oAuth2 process each time.
Using Postman allows you to avoid this and also take advantage of a number of other features of that application. One nice feature is the ability to generate access tokens with ease so that they do not need to be refreshed each time you run an endpoint. (You will still need to refresh them after the allotted 60 minute life but that should give you plenty of time to run a number of endpoints)
This post shows you how to set up Postman for oAuth2 in the simplest way possible. I am not an expert in Postman and there may well be things that I have missed that could make the process even easier. Let me know in the comments if you do something differently!
Setup your application
It is probably wise to have a separate Blackbaud application for Postman rather than using an application that you use in production.
This is my very basic app. For Postman you do not need a live redirect URI but you do need one as the SKY OAuth2 process requires that the value you send in matches a value on your app.
In my postman I have a collection of Sky API endpoint calls. You are able to add authorisation details to the main folder and have each endpoint inherit the credentials from that rather than having to enter them each time.
When I click on the Sky API link I can enter my credentials for the whole folder.
Hopefully most of the values are self-explanatory. You should start with the section “Configure New Token”.
Token Name: Just give your token a name so that you recognise it.
Grant Type: Authorization Code
Callback URL: This is one of the values that you have in your SKY app
Auth URL: https://oauth2.sky.blackbaud.com/authorization
Access Token URL: https://oauth2.sky.blackbaud.com/token
Client ID: This is the Application Id from your SKY app
Client Secret: From your SKY app
Scope: This is not currently used by the SKY API
State: You could put a value here but it has no real use in the context of Postman
Client Authentication: Send as Basic Auth Header
Press the “Get New Access Token” button. This will prompt you to log into Blackbaud and go through the OAuth2 process. It will then save a token in the Current Token area. This is then used by your calls.
Setup an individual endpoint call
Now that you have set up authorisation, you can proceed to try a call. You will still need to add your subscription id to the header as shown. (If anybody knows of a way to add that value on the folder level let me know!)
Put the URL in the address box and change the authorisation to inherit from parent as shown below
On the headers tab, add the bb-api-subscription-key
This can be found on your developer account here: https://developer.blackbaud.com/subscriptions/
Then you are ready to press the Send button to retrieve data from SKY API