Authentication Scopes

Authentication scopes are included as a parameter in the web url you send users to in the OAuth authentication flow. Your application can request multiple scopes by separating them with a space.

e.g. scope=messages:connect burners:read

Here’s a list of all the valid scopes your application can request:

burners:read provides access to the GET burners endpoint with information about a user's active burners.
burners:write allows the app to modify burner settings parameters such as rings and notifications.
contacts:read gives the app access to GET contacts endpoint to read info about contacts.
contacts:write allows the app to create new contacts or modify existing ones on the user's behalf.
messages:connect provides access to POST to messages endpoint to send messages on behalf of the user. Will trigger a burner selection page in the OAuth flow unless the burner_id parameter is included in the call to authorize. See discussion below for more information. When authorized, this scope will also allow your application to begin receiving outgoing webhooks from authorized Burners.
Global scopes

Most of the authentication scopes are global, meaning that they give your application access to burner and contact information that is at the global user account level, not tied to a specific Burner. The global scopes are:

  • burners:read
  • burners:write
  • contacts:read
  • contacts:write

Requesting any of these scopes will allow your application to read and write information that is not restricted to a specific burner.

For example, if your application requests the burners:write scope, it will be able to modify information for any of the user’s Burner numbers.

Burner scopes

However, the Burner API also has the concept of a scope that is only valid for a limited number of Burners that the user has specifically given your application access to.

There is only one local scope:

  • messages:connect

If your application requests the messages:connect scope then, when the user is authorizing your application, they will be presented with an option to choose one or more of their active burners to authorize.

The access token you receive will allow you to call the messages api endpoint only for burners that have been authorized by the user.

When you make the api call to to receive the access_token your application, if requesting a Burner scope will receive a list of connected_burners in the response, along with the access_token. Your application should store this information.

Here’s a full example response from the oauth_access endpoint if you include the messages:connect scope:

Outgoing webhooks

You might have noticed the outgoing_webhook_url in the response above. When messages:connect is authorized, your application will begin receiving outgoing webhooks from the authorized Burner. This url will be the same as the webhook url that was configured with your application. See the outgoing webhooks page for more information.

Mixing global + local scopes

Mixing global and local scopes is perfectly acceptable.

If your application requested the scope burners:read,messages:connect it would be authorized to read information about all of the user’s active burners and send messages from only the burner specified by the user.