Bloomerang OAuth Reference Guide

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_id`	Required	Your unique identifier is given to you by Bloomerang.
`response_type`	Required	This must be set to “`code`”
`state`	Required	This 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_uri`	Optional	This 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 compared against the registered redirect_uri. The redirect_uri must not include a fragment component.
`scope`	Optional	If 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:

`code`	An authorization code that 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. After the ten
minutes have 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_type`	Required	This must be set to “`authorization_code`”
`code`	Required	This must be the authorization code returned from the grant request.
`redirect_uri`	Required	This 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_token`	A string value is used to authorize your requests to the API on behalf of the user who granted access.
`token_type`	This will always be “`Bearer`“
`expires_in`	The number of seconds in which this token will expire
`scope`	The scope associated with the access token
`refresh_token`	A 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 Parameters:

`grant_type`	Required	This must be set to ” `refresh_token` ”
`refresh_token`	Required	This must be the refresh_token associated with the most recent access_token acquired for this Bloomerang user.
`scope`	Optional	Must 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_token`	A 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_in`	The number of seconds in which this token will expire
`scope`	The scope associated with the access token
`refresh_token`	A 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

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.