Implicit Flow

  • Introduction

    The implicit grant is meant for applications where API calls are made from the client, typically within a browser using JavaScript. Since API calls are made from the client, they are inherently less secure and do not involve the exchange of an application secret. The access tokens that are issued are short-lived and no refresh tokens are provided, so the user must re-authorize your application when the token expires.

    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.

    Implicit Grant Flow

  • 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):

    https://oauth2.sky.blackbaud.com/authorization

    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 state parameter 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

    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:

    Authorization Consent Form

    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_uri that 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 Authorization header 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 bearer.
    expires_in integer The time period (in seconds) in which the access token is valid.
    state string The value of the state parameter 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.

    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, access_denied).
    state The value of the state parameter 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 Authorization request header with a value of Bearer, followed by a space and the access_token value.

    You will also need to provide your subscription key to the SKY API via the bb-api-subscription-key header. 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.

    Sample Request

    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.