Developers

Overview

Several API endpoints in the Brainstorm API allows for adding content to Brainstorm. This may include:

  • Adding an idea
  • Posting a comment
  • Adding skills or interests to a person profile

To submit content to Brainstorm (on behalf of a user), one will need to either:

  • have the user's AccessKey,
  • or handle raw email & passwords of users

Passing the credentials to the Brainstorm API requires you to add a special header, X-On-Behalf-Of to your HTTP request which you will set the Base64 encoded credential. The credential may either be the AccessKey or the user's email & password combination.

NOTE: Both will need to be Base64 encoded

How to get an AccessKey

The most secure way to act on behalf of Brainstorm users is through the two channel authentication model. This requires the Brainstorm user to get a PIN code that the API can then use to associate with his or her application. After associating the PIN, an AccessKey gets returned that may be used for on-behalf-of requests.
To instruct your users to retrieve the access token, direct the user of your application to:

/api/authentication/getpin

After the user has his or her PIN code, ask the user to pass that code to your application where you can make another API call to associate that PIN with your app. As a result, you will receive the access token that you can pass use to act on behalf of the user by setting the X-On-Behalf-Of header with. NOTE: you must also Base64 encode the access token.

To associate the PIN code with your apikey, submit an HTTP POST request to:

/api/authentication/associatepin

You will need to include your API Key, as well as the following parameters: pin=[pin received from '/api/authentication/getpin'] as a POST parameter. As a result, you should see a result like this:

        <AccessToken xmlns="http://schemas.datacontract.org/2004/07/Brainstorm.Model.DTO.Auth" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
          <AccessKey>D9ABF5C273C1010E</AccessKey> 
          <!-- not used --> <AccessSecret>D8F56CD9DC34511A5070B6B4</AccessSecret>
          <AppName>JIRA Integration Widget</AppName>
          <AssociatedWith xmlns:a="http://brainstorm.intuit.com">
            <a:Id>11362</a:Id>
            <a:DisplayName>Bryant Chou</a:DisplayName>
            <a:EmailWork>Bryant_Chou@intuit.com</a:EmailWork>
            <a:Location/>
            <a:Phone>650-944-3796</a:Phone>
            <a:PhotoExists>true</a:PhotoExists>
            <a:PhotoUrl_36x36>/Files/Tenant_1/DirPhotos/Small/11362_3.jpg</a:PhotoUrl_36x36>
          </AssociatedWith>
          <CreatedOn>2011-08-10T00:44:27.1118665Z</CreatedOn>
        </AccessToken>
    

Notice that in addition to the AccessKey you also have some information about the user, including the name, email, and photo URL. After you get the AccessKey, you can Base64 convert it and set it to the X-On-Behalf-Of header.

Email & Password

If you cannot use access tokens, you may also get the user's email and password and submit that as part of the X-On-Behalf-Of header. The value of the header should be

Base64({email}:{password})

Here is some sample C# code to assemble the header:

        Headers["X-On-Behalf-Of"] = ConvertToBase64(string.Format("{0}:{1}", email, password));
    

If your API key is admin enabled, you may use the X-On-Behalf-Of-User header in place of the normal header. Using this header doesn't require the password to be passed along.

Base64({email})