OAuth2 Authentication Guide

By Thomas Pendergrass,


Authenticating with BombBomb allows you to securely utilize our API on behalf of BombBomb users. To complete the authentication process, you must create an OAuth Client, get a BombBomb user’s approval, and acquire tokens. This guide will walk you through that process and also inform you on how to use the tokens once you have them.

Note: In this guide, text highlighted in red will represent variables specific to 

Create an OAuth Client

An OAuth Client represents your application. You must have a BombBomb account in order to create a client.

To create a client, use the “Create an OAuth Client” interface.

Create an OAuth Client

Click the OAUTH button at the bottom right to set your scope. select the all:manage button so the interface can generate your OAuth Client. Click the Authorize button.

You will be redirected to an authorization page. you will need to log in to your account and click ‘Allow’.

Once authorized, fill in the parameters. The ‘name’ parameter allows you to easily identify your OAuth Client, in the case that you have more than one. The ‘redirectUri’ parameter is the web page the user is sent to after approving your request for an access token.

Click on the ‘Try’ button to view information about your new OAuth Client. You will need client_secret, redirect_uri, and identifier to make authenticated API requests.

Get User Approval

For users to grant access to your client, send them to the following hyperlink:


Users will be directed to a screen stating that your client would like permission to access their account. Once the user accepts the request, they will be sent to the redirect URI you specified. The URI will contain a parameter named ‘code’ which contains the URL encoded authorization_code. You will need to decode the authorization_code for use in acquiring an access token.

Acquire Tokens

You will need to send a POST request to the following url:

    grant_type : authorization_code,
    client_id : identifier,
    client_secret : client_secret,
    redirect_uri : redirect_uri,
    code : authorization_code

You will receive a response containing an access_token and refresh_token, along with the remaining time the access token is valid (in hours).

    token_type : Bearer,
    expires_in : 3600,
    access_token : access_token
    refresh_token : refresh_token

Keep the access_token and refresh_token in a secure location.

Use Tokens

Use the access token for any API requests you make pertaining to the user. Do so by adding an Authorization header to your request.

Bearer access_token

The access token will expire after a set amount of hours. When this occurs, you can use the refresh token to gain a new access token. To use the refresh token, POST to the following url:

    grant_type : refresh_token,
    client_id : identifier
    client_secret : client_secret
    refresh_token : refresh_token

You will receive a new access_token and refresh_token.