What are scopes and access tokens, and how do I request more access from a sign-in provider?

Scopes are the permissions your website or app asks a sign-in provider for. By default, Bread & Butter asks each provider only for the visitor's basic profile and email address. If your app needs more, such as a visitor's calendar, inbox, files or code repositories, you can request extra scopes for each provider you've set up with your own app.

In short: A scope names a resource your app wants to use on the visitor's behalf, like their Google Calendar or their Dropbox files. Every provider you set up with your own app requests the basic profile and email address scopes by default. To ask for more, add them in the Scopes section of that provider's Advanced Settings in Bread & Butter. When a visitor signs in, the provider shows them what you've asked for and lets them accept or decline. If they accept, turn on Return Authorization Data and Bread & Butter passes the visitor's access token to your site, which your app uses to reach that resource. Bread & Butter never stores access tokens. Some providers, such as Apple, Basecamp and Twitch, don't support extra scopes.

How scopes work

1. You add the scopes your app needs to a provider's settings in Bread & Butter.
2. When a visitor signs in with that provider, the provider shows them the permissions you've requested.
3. The visitor chooses whether to allow them.
4. If they allow them, the provider issues an access token, which your app uses to make requests on the visitor's behalf, for example to read their calendar or save a file to their Dropbox.

Only ask for what your app needs. Each extra permission is one more thing a visitor has to agree to, and long permission lists can put people off.

Add scopes to a provider

Extra scopes are set on a provider you've connected with your own app credentials, not on the default Sandbox connection.

1. In Bread & Butter, go to Settings, then Global Conversion Methods.
2. Edit the provider you want to change.
3. In Advanced Settings, find the Scopes section and enter the scopes you need, using the names from the provider's documentation below.
4. Click Save.

Some providers also require you to request or enable the same scopes in their own developer portal, and may review your app before they allow them. Check the provider's documentation.

Get the visitor's access token

An access token is what your website or app uses to make requests to a provider on a visitor's behalf. To receive it:

1. In Bread & Butter, go to Settings, then Global Conversion Methods, and edit the provider.
2. In Advanced Settings, turn on Return Authorization Data.
3. Click Save.

Each visitor's access token is then returned to your website or app when you validate their sign-in on your server, as shown in the DIY Quick Start guides for PHP, Node.js and .NET. To use the token, follow the provider's own documentation for the resource you want to reach.

Return Authorization Data isn't available for Twitch or for SAML enterprise connections.

Keep access tokens secure

Bread & Butter doesn't store your visitors' access tokens. It only passes them securely from the provider to your website or app. Once you have them, they're yours to protect:

• Store access tokens securely.
• Make sure no other application can read them.
• Only send them over HTTPS.

Available scopes by provider

Related

• Conversion Options Overview
• What is a client secret, and what do I do if one is compromised?
• What is a Custom Auth Domain, and how do I set it up?
• How to get User Profile information