Using OAuth 2.0

OAuth 2.0 is a protocol that lets your app request authorization to read or modify information from a user’s Burner account, or create text messages on the user’s behalf without having to ask for their password.

You’ll need to register your app before getting started. A registered app is assigned a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should not be shared.

To register your app and obtain your credentials fill out this form.

Burner uses OAuth 2’s authorization grant flow to issue access tokens you can use to perform actions on behalf of the user.

Authorization

Your app should redirect users to the following URL:

https://app.burnerapp.com/oauth/authorize

and include the following GET parameters:

client_id issued when you created your app required
scope permissions to request (more here) required
redirect_uri must match the originally submitted URI required
state unique string to be passed back upon completion optional
burner_id a known burner id optional

The scope parameter is a comma-separated list of OAuth scopes that determines which parts of the user’s Burner accounts you can access from your application.

You can view the full list of scopes here.

The state parameter can be used to avoid forgery attacks by passing in a value that’s unique to the user you’re authenticating (for example a user id) and checking it when auth completes.

The burner_id parameter can be used to automatically connect a known burner id to the app after authorization. If a burner id is provided, the OAuth flow will skip the burner selection page and automatically connect the provided burner to the app after authorization. This case should be primarily used by clients to initialize OAuth flows from within a specific Burner context. The messages:connect scope is required in order for this parameter to work as intended.

If the user completes the authorization step, Burner will redirect the user to your app’s specified redirect_uri with a code as a GET parameter. If you passed in a state parameter above, then that will be returned as well and you can ensure that the values match before proceeding to prevent forgery.

Once you have the authorization code you can exchange it for an access code you can use to perform actions on behalf of the authorizing user.

Authorization codes will expire 10 minutes after they are issued.

If the user denies your request from the authorization screen, Burner redirects back to your redirect_uri with an error parameter: http://yourapp.com/oauth?error=access_denied

Make an api call to:

https://api.burnerapp.com/oauth/access

with the following paramters:

clientId issued when you created your app required
clientSecret issued when you created your app required
code a temporary authorization code required
redirectUri must match the originally submitted URI required

and you will receive a JSON response containing an access token. You will also receive a node containing information about the initial burner(s) connected to your app if you requested a messages:connect scope.

The response should look like this:

{
  "access_token":"2c6241b7-1830-4fb1-866d-ab604e22c490",
  "scope":"messages:connect,burners:read",
  "connected_burners": 
  [
    {
      "id":"3b0794ed-a2a0-409e-bbe6-519a141192b2",
      "name":"Craigslist",
      "status":"active",
      "outgoing_webhook_url":"http://yourapp.com/webhook_url"
    },
    {
      "id":"169e4547-3925-46ad-a42f-aae64b1f9051",
      "name":"Random",
      "status":"active",
      "outgoing_webhook_url":"http://yourapp.com/webhook_url"
    }
  ]
}

That’s it! Once you have the access_token your application can then include it calls to API methods on behalf of the user.

You might want to check out the api docs and see some of the fun things you can build.