How to Integrate with the Bloomerang REST API

Registering Your Application with Bloomerang

First, you must register your application with Bloomerang. Bloomerang will need the following information via email:

  • Application name
  • Description
  • Website URI
  • Privacy policy URI
  • Terms of service URI
  • Redirect URI – this is a URI to your application that Bloomerang will redirect users to when the user authorizes your application to access Bloomerang

Bloomerang will generate and send you a client ID and secret key. The secret key must be protected from disclosure.

Request Access to the User’s Account

Starting from your site, send the user to Bloomerang, making a GET request
to https://crm.bloomerang.co/Authorize.

Request URI:
GET https://crm.bloomerang.co/Authorize

Request Parameters:

client_idRequiredYour unique identifier given to you by Bloomerang.
response_typeRequiredThis must be set to “code
state RequiredThis is an arbitrary string value. We’ll return this value exactly as provided. Your application should verify that the value we return matches the value you sent for CSRF protection.
redirect_uriOptionalThis must match the redirect_uri registered with your client_id in Bloomerang’s system. It may include an “application/x-www-form-urlencoded” formatted query component. The query component is removed when comparing against the registered redirect_uri. The redirect_uri must not include a fragment component.
scope OptionalIf not provided, this will default to the highest available scope allowed for the account. Values may be one of “Standard,” “StandardEditFinancialData,” and “OrgAdmin.”

Response Parameters:

codeAn authorization code which can be used to retrieve a token associated with the user’s account.
state The value you provided for the state on the request

If there are issues with the client_id or the redirect_uri parameters, Bloomerang will display an error page. For any other errors, we’ll redirect the user back to your redirect_uri with an error message and a state value matching the one provided in the request. Once the user has granted you access to their account, we’ll direct them to the redirect_uri with an authorization code and a state value matching the one provided in the request.

Example Request


GET https://crm.bloomerang.co/Authorize 
        ?response_type=code
        &client_id=s6BhdRkqt3 &state=kgYSeM8YHPHqxkbt
        &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
    

Example Valid Response


302 https://client.example.com/cb
        ?code=SplxlOBeZQQYbYS6WxSbIA
        &state=kgYSeM8YHPHqxkbt
      

Example Error Response


302 https://client.example.com/cb
        ?error=access_denied
        &state=kgYSeM8YHPHqxkbt
        

Retrieve an Access Token for the Account

Once the user has granted you access and you have the authorization code, you’ll have ten minutes to send a POST request to https://api.bloomerang.co/v2/oauth/token. Once the ten minutes has expired, you’ll need to re-request access from the Bloomerang user. The authorization code may only be successfully used once. Attempts to re-use a previously used authorization code will result in the revocation of any access tokens associated with the code. Errors will be returned in application/json format and will contain an “error” property specifying the type of error and an error_description property with human readable text providing more information (e.g. { "error": "invalid_scope", "error_description": "The provided scope is invalid." }). Valid responses will include a JWT token, which contains the data you’ll need to make requests to the Bloomerang API on behalf of the user. Authentication Requirements: Basic Auth, with your client Id as the username and client secret as the password.

Request URI:
POST https://api.bloomerang.co/v2/oauth/token

Request Parameters:

grant_typeRequiredThis must be set to “authorization_code
codeRequiredThis must be the authorization code returned from the grant request.
redirect_uriRequiredThis must exactly match the value provided in the Authorization call requesting access to the user’s account (if no redirect_uri was provided in that call, this must exactly match the one registered with your client record).

Response Parameters:

access_tokenA string value used to authorize your requests to the API on behalf
of the user who granted access.
token_type This will always be “Bearer
expires_inThe number of seconds in which this token will expire
scope The scope associated with the access token
refresh_tokenA token which can be used to generate another access token once the current one expires (the same refresh token may not be used multiple times; doing so will revoke all access tokens and refresh tokens in the chain)

Example Request


POST https://api.bloomerang.co/v2/oauth/token
    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &code=SplxlOBeZQQYbYS6WxSbIA
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
    

Example Response


{
  "access_token": "eyJhJGciOiJIUzG1NiIsd6fInR5cCI6IkCJ9.eyJoHdRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zeXN0ZW0i.kKYXIhkUap74f9Rgh2H-aIGaOyX-UXyrIgzLkF9w3NA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "OrgAdmin",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA="
}

Refreshing an Access Token

Once an access token expires (or is about to expire), you may regenerate another access token without having the user re-grant access by using the refresh_token provided to you alongside the expired or expiring access_token.

The refresh tokens expire in 90 days. Any attempt to use a refresh token that has already been used will result in the revocation of all tokens associated, and you will need the user to grant you access again. You should discard the current refresh_token once you receive a new access_token/refresh_token pair.

Authentication Requirements: Basic Auth, with your client Id as the username and client secret as the password.

Request URI:
POST https://api.bloomerang.co/v2/oauth/token

Request Parameters:

grant_typeRequiredThis must be set to “refresh_token
refresh_tokenRequiredThis must be the refresh_token associated with the most recent access_token acquired for this Bloomerang user.
scopeOptionalMust not be greater than the scope originally granted, but a lesser scope may be provided. If omitted, the new access token will have the same scope as the previous access token.

Response Parameters:

access_tokenA string value used to authorize your requests to the API on behalf of the user who granted access.
token_type This will always be “Bearer”
expires_inThe number of seconds in which this token will expire
scope The scope associated with the access token
refresh_tokenA new refresh token. This can be used to generate another access token once the current one expires.

Example Request


POST https://api.bloomerang.co/v2/oauth/token
        Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
        Content-Type: application/x-www-form-urlencoded
        
        grant_type=refresh_token
        &refresh_token=tGzv3JOkF0XG5Qx2TlKWIA=
      

{
  "access_token": "eyJhJGciOiJIUzG1NiIsd6fInR5cCI6IkCJ9.jYe580aKdJnvl1soZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zeXN0ZW0i.kKYXIhkUap74f9Rgh3saGaOyXX3oEyrIgzLkF9w3NA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "OrgAdmin",
  "refresh_token": "oTIOrksb0X2dKB98vz="
}

Using the Access Token

Once you have a valid access_token, simply send a “Bearer Token” authorization header with that access token along with each request to the API.

curl -H 'Accept: application/json' -H "Authorization: Bearer eyJhJGciOiJIUzG1NiIsd6fInR5cCI6IkCJ9.jYe580aKdJnvl1soZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zeXN0ZW0i.kKYXIhkUap74f9Rgh3saGaOyXX3oEyrIgzLkF9w3NA" https://api.bloomerang.co/v2/endpoint

Once the access token expires (or shortly before), call the refresh token endpoint to retrieve a new access token.