Environment-Level Authorization Questions

Steven Cinquegrana
Steven Cinquegrana
Tenth Anniversary Kudos 2 Name Dropper Participant
in SKY Developer General Discussions
After the change last year from Tenant-Level to Environment-Level SKY API authorization, we changed our SKYLib.NET API library's internal authorization handling accordingly.


However, we've found a couple of tricky bits which I'd like some clarification on please.


1. Our subscriptions page looks like this:

d54edfb902486d527eb1d0d2bdbb7e43-huge-bb


(Don't worry about the Payments API; we were told that we couldn't have developer access to it for some reason, which I find a bit strange considering that it would be nice to be able to test it. Not relevant here in any case.)


Note the APIs included section: this includes every API that we have access to using the account Subscription Keys. Note that the list includes the School (Beta) API.


2. I would expect that all of these APIs should be accessible using the same (environment-level) authorization. That is, the same authorization token set should be able to be used for all and any of these APIs singly or in combination.


3. However, when we authorize, we're presented with a choice of two Environments:

9a91735771547a8974c51a8b3350a63b-huge-bb

or

dbb78ededab7a95dcde2562a95e7576a-huge-bb


If we select anything other than EDU Sandbox/Environment 1 for the School API, we get an error, and vice-versa.


This seems somewhat counter-intuitive to me; if the API is included in our Subscription, shouldn't the same authorization credentials cover all APIs within that Subscription?


Or can a Subscription cover more than a single Environment, even if this isn't explicitly detailed on the Subscriptions page?


Can someone please clarify? As it is, we seem to have gone from maintaining separate authorization credentials for multiple Tenants to still having to maintain them for multiple Environments. Is this correct?


Cheers and thanks,

Steve Cinquegrana | CEO and Principal Developer | Protégé Solutions

 

Comments

  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hey Steve,


    Environment level authorization means that the user is giving consent for an application to make API calls across the environment, which may contain multiple Blackbaud solutions (check out this article for a primer on the Blackbaud Customer Data Model). The vast majority of customers have one environment, so the change enables the access token that is generated to be used for any of the APIs included in the subscription. The change benefits those with multiple Blackbaud solutions where the application would need to call multiple APIs.


    For example, if a customer has RE NXT and FE NXT in a single environment, the user authorizes once, and the access token can be used to call Constituent and General Ledger APIs (that are included in the Standard APIs subscription). Before the change, the user had to authorize RE NXT to get an access token to call Constituent and then authorize FE NXT separately to get a different access token to call General Ledger.


    However, the authorization is still for a single environment. So in your case where you have 2 environments, presumably with Education Management in both, you would still need access tokens to call the School API in each environment.


    Hope that helps.


    Thanks!




     
  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant
    Thanks, Ben‍,

     

    ... the change enables the access token that is generated to be used for any of the APIs included in the subscription.

    Is this correct? Did you mean to say "... in the environment"? Otherwise, what we have already should be ok; we have the School/Education Management API in the same subscription as the everything else (bar the Payments API).

     

    ... presumably with Education Management in both [environments]

    I think we only have School/Education Management in one environment, the EDU Sandbox environment, hence the problem when we try to use the token credentials for the other environment. Could you confirm my assumption on this please?


    At the moment, the subscriptions page doesn't indicate environment segments. Could this be added so we know which APIs are in which subscription and environment?


    Cheers, Steve

     
  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hey Steve,


    I think there is an opportunity here to provide more clarification in our docs. The access token can be used for any of the APIs included in the subscription for a given environment. Subscriptions are not tied to an environment. Said another way, your API access keys (aka subscription key which can be obtained from the My Subscription page) enables you to make calls to a specific set of APIs (the APIs included list). The access token that is obtained via the OAuth process is tied to a specific environment. You can say that the access key (aka subscription key) tells you what APIs you can call, the access token tells you which environment you have been authorized to call those APIs.


    You can call the School API because it's included in the Standard APIs subscription. However, the access token in the OAuth specifies the environment where you can call the School API.


    Does that make sense?
  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant
    Ok, thanks Ben‍ . That's kinda what I thought but it would be pretty useful to be able to see the Environment breakdown on the Subscriptions page. The only way we discern this currently is by trying to authorize and having to select the alternate environment.


    Lastly, to confirm, an app working in multiple Environments will therefore need to manage separate Authorization token sets for each Environment, correct? But if a subscription covers all of the Environments owned by the subscription what is the reason to segment by Environment? To restrict user access?


    Cheers, Steve

     
  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hey Steven Cinquegrana‍,

    Lastly, to confirm, an app working in multiple Environments will therefore need to manage separate Authorization token sets for each Environment, correct?

    Yes. The access_token is obtained when a user authorizes the app to make calls to a specific environment. If the app needs to work in multiple environments, it needs to be connected to each environment and authorized separately. Your app needs to know which environment to call.

    But if a subscription covers all of the Environments owned by the subscription what is the reason to segment by Environment? To restrict user access?

    I'm not fully understanding this. A subscription doesn't "cover all of the Environments owned by the subscription". The subscription isn't tied to any environment. The subscription is tied to a developer account and allows you (the developer) to call a set of APIs. The subscription is essentially Blackbaud saying that you are allowed to use SKY API.


    However, you cannot make API calls with your subscription key (aka access key) alone because your app needs an environment to make API calls to. Even though Blackbaud has provided a subscription, you still need authorization from a customer to make calls to an environment. To do that you need a customer to connect your app to an environment, which can then be selected by a user on the OAuth form, which will then give your application an access_token to make API calls to that environment.


    When you say "what is the reason to segment by environment", do you mean, why does a user need to authorize twice if they have two environments? There are a few different use-cases where a customer can have multiple environments, and I don't think it can be assumed that if you authorize one, you always want to authorize the other. For instance, you may want to authorize an application in a test environment, but not the production environment. Or the two environments may be separate departments that operate independently but under the same org umbrella.


    Not sure if that's what you're after but I hope that helps.

     
  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant

    ... cover all of the Environments owned by the subscription

    Perhaps "owned" wasn't the right term; what I meant was the environments that the subscription had rights to, could access data from, etc.


    In any case, you have answered the question, thanks, Ben‍.


    Cheers, Steve

     
  • Steven Cinquegrana
    Steven Cinquegrana
    Tenth Anniversary Kudos 2 Name Dropper Participant
    With the School API moving from beta to live, I would have expected that our general developer environment credentials would now work (rather than just the beta EDU Sandbox Environment 1 ones).


    But I just checked and no go.


    I still have to select the EDU Sandbox environment, otherwise I get the dreaded-and-useless 500 Internal Server Error.


    Assuming we're not the only organization with a sandbox environment, will these be switched en masse to the standard developer environments? If so, when? If not, what do we need to do?


    Thanks.

     
  • Ben Wong
    Ben Wong Blackbaud Employee
    Tenth Anniversary Kudos 3 Name Dropper Participant
    Hey Steven Cinquegrana‍,


    The School API moving to GA doesn't change anything in terms of the subscription keys or what access the application has to environments. We don't want to change what access the applications have en masse, because that should be done by an authenticated user.


    It sounds like you have two environments, one with RE NXT and FE NXT, and another one with Education Management. Since you have two different environments, applications will need to be authorized for each one independently. I believe technically you could have a single environment to contain all your Blackbaud solutions, which would mean that you only need to authorize that single environment.

Categories