Like the Authorization Code Flow, the implicit flow starts by redirecting the user's browser from your application to our Authorization URL. The user will login (using the Blackbaud or Google credentials), confirm that it's OK for your application to access their data, and then we'll redirect back to you with an access token that you can immediately use when making API calls on that user's behalf.
Since this is a redirection-based flow, your application must be able to interact with a web browser and receive incoming requests (via redirection) from our OAuth endpoints.
Step 1 – Request authorization
Initiate the authorization process by redirecting the user's browser to our authorization endpoint. You can choose to do this as a step in your application's login process or in response to some user action in your app (like a button click):
When navigating, you'll need to include a few parameters in the query string. These parameters are fully described in RFC-6749 section 4.1.1:
Query parameter Description client_id Required. The Application ID value that we provide when you register your application. This value uniquely identifies your application. See RFC-6749 section 2.2. response_type Required. The value must be set to
token. This indicates that the access token should be returned in the fragment of the redirect URI.
redirect_uri Required. The URI to redirect to after the user grants or denies permission to your app. This value must exactly match one of the Redirect URI values you specify when you register your application, including any capitalization, trailing slashes, etc. See RFC-6749 section 3.1.2. state Optional, but recommended. The
stateparameter is an opaque value that you can provide when requesting authorization that will be echoed back to you when the user grants or denies permission to your app. You can then validate this parameter to ensure that an incoming redirect is the result of an authentication request that originated in your application. This provides protection against Cross-Site Request Forgery (CSRF) attacks. You can also use this parameter to maintain some state between the authorization request you initiate and the incoming navigation to your redirect URI for the purposes of returning the user to tbe most appropriate location within your app. See RFC-6749 section 10.12
environment_id Optional. The
environment_idparameter can be used to filter the list of eligible environments shown during the user authorization step. This filter is useful when the user is already operating in the context of an environment, such as within a SKY API user interface add-in. We'll have more information on environments and add-ins in the near future.
Note: to facilitate local development, we allow the use of http and localhost or the localhost IP (127.0.0.1). In production however, we require the use of https for proper security when redirecting.
A sample authorization request looks like this (with extra line breaks for display purposes only):
https://oauth2.sky.blackbaud.com/authorization? client_id=E140BF29-A528-4048-91A9-83BCB01B7FE2 &response_type=token &redirect_uri=https://www.example.com/oauth2/callback &state=fdf80155
Step 2 – User authorization
In this step, we'll ask the user to log in (using their Blackbaud or Google credentials). We'll then ask them if it's ok for your application to access their Blackbaud data:
If the user has access to more than one customer's data, they'll select the customer (tenant) to which they are giving your app permission.
Step 3 – Access token provided
After the user grants (or denies) your authorization request, we'll redirect the browser to the
redirect_urithat you specified in the request (in the above example, we'll redirect the browser back to your application at https://www.example.com/oauth2/callback).
If the user granted your app permission, the URL fragment will contain the following fields:
Field Type Description access_token string An access token to be used when making calls to the SKY API. The access token should be provided in the standard
Authorizationheader in the form of
Bearer token(note the separating space).
token_type string Indicates the type of token issued, and will always contain the value
expires_in integer The time period (in seconds) in which the access token is valid. state string The value of the
stateparameter you supplied in the initial authorization request.
tenant_id string The ID of the specific Blackbaud customer (tenant) whose data can be accessed using the access token. When the user grants permission to your application, they do so in the context of their organization. The tokens we issue can only be used to access that customer's data. We provide this value to you for informational purposes only - it is not used when calling the SKY API. You may store this value in your application along with the user's access token. tenant_name string The name of the specific Blackbaud customer (tenant) whose data can be accessed using the access token. When the user grants permission to your application, they do so in the context of their organization. The tokens we issue can only be used to access that customer's data. We provide this value to you for informational purposes only - it is not used when calling the SKY API. You may store this value in your application along with the user's access token. legal_entity_id string The legal entity identifier. A legal entity represents a Blackbaud client (organization or individual) who can try out or purchase the products, services, and solutions Blackbaud provides. We provide this value to you for informational purposes only - it is not used when calling the SKY API. You may store this value in your application along with the user's access token. legal_entity_name string The name of the legal entity. environment_id string The environment identifier. An environment is a logical group of products and service instances that a legal entity is entitled to. We provide this value to you for informational purposes only - it is not used when calling the SKY API. You may store this value in your application along with the user's access token. environment_name string The name of the environment. user_id string The unique identifer of the authenticated Blackbaud user in whose context the access token is issued. This value can be used to correlate Blackbaud users with users in external systems. Reminder: The Implicit Grant Flow provides a short-lived access token that expires in 60 minutes. A refresh token is not provided, so when the token expires your application should re-authorize the user again.
Successful redirect response example (with extra line breaks for display purposes only):
https://www.example.com/oauth2/callback# access_token=1d57284f025...4975d &token_type=bearer &expires_in=3600 &state=fdf80155 &tenant_id=E27DD7B6-6B71-4689-8B2C-60A74F243966 &tenant_name=Raiser%27s%20Edge%20NXT%20-%20Blackbaud%20%28Developer%20Sandbox%29 &legal_entity_id=p-AaBbCcDdEeFfGg987654321", &legal_entity_name=Blackbaud%20Developer%20Sandbox &environment_id":"p-abcdef1234567890ABCDEFG", &environment_name=Blackbaud%20Developer%20Sandbox%20Environment
If the user denied your permission request, the query string will contain the following parameters:
Query parameter Description error The reason that authorization failed (for example,
state The value of the
stateparameter you supplied in the initial authorization request.
For example (with extra line breaks for display purposes only):
https://www.example.com/oauth2/callback? error=access_denied &state=fdf80155
For more information on commonly encountered authorization problems, see common authorization issues.
Step 4 – Call the SKY API
The access token allows you to make requests to the SKY API on a behalf of a user. When calling the API, provide the access token using the standard
Authorizationrequest header with a value of
Bearer, followed by a space and the
You will also need to provide your subscription key to the SKY API via the
bb-api-subscription-keyheader. You can use either the primary or the secondary key (both are equally functional), and both can be found on your developer profile page.
For more information on providing these headers, see request headers.
GET https://api.sky.blackbaud.com/constituent/constituents/280 HTTP/1.1 Host: api.sky.blackbaud.com Authorization: Bearer eyJ0eXAiOiJKV1...CTtP0CQ bb-api-subscription-key: 77f137116...480d633
Step 5 – Next steps
For more information on implementing the implicit flow, check out our code samples.