Your customers are your Bread & Butter

What are you doing to get to know them?

START YOUR FREE TRIAL

Introduction

BreadButter.io is a set of tools to help you know your users and convert them faster. Adding the BB JSL to your website instantly provides you with tools to identify visitors to your page and quickly let them authenticate with various identity providers (IDPs) like Google, Microsoft, Okta, etc.

Getting Started

Get up and running with our client libraries and start developing your Bread & Butter integration.

Client Only Libraries

Client only libraries are used to initiate the authentication process and handle any of the custom UI portions of the login workflow. Client based libraries cannot retrieve the details of an authentication so please use one of the Server side libraries to complete your authentication workflows.
JavaScript Library (JSL)

Server Libraries

Server side libraries are used to facilitate the post-authentication workflows.
PHP | .NET

Installation

PHP

# Maven

1
2
3
4
5
6
7
8
<dependency> <groupId>com.breadbutter</groupId> <artifactId>breadbutter-java</artifactId> <version>3.0.0</version> </dependency> Copy

# Via command line

nuget install BreadButterClient
Copy

# Via Package Manager

PM> Install-Package LogonLabs.Client
Copy

# Via Visual Studio

  1. Open the Solution Explorer.
  2. Right-click on a project within your solution.
  3. Click on Manage NuGet Packages…
  4. Click on the Browse tab and search for “BreadButter”.
  5. Click on the BreadButter.Client package
  6. Select the appropriate version in the right-tab and click Install.

# Via Command Line

npm install LogonClient
Copy
pip install breadbutter-python
Copy
composer require breadbutter/breadbutter-php
Copy

Quick Start

Prior to coding, some configuration is required in App Settings.

The JavaScript Library

The BreadButter JavaScript Library (JSL for short) gives you all of the tools to get started converting your users. It handles all the design elements and renders authentication options directly in your existing page with minimal configuration

Download

https://cdn.breadbutter.io/dist/breadbutter.3.0.0.142.min.js

Continue With Configuration

“Continue with” provides your site with Bread & Butter’s signature Widget. Appearing anchored as an overlay it provides the user with a simple method to identify themselves with your system without having to take take them away from their active page.

Remember to replace APP_ID with the one for your application found here





Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!DOCTYPE html> <html> <head> <title>Bread & Butter Sample</title> <script> window.initBreadButter = function() { BreadButter.configure({ app_id: APP_ID }); BreadButter.widgets.continueWith(); }; (function(d, s, id){ var js,fjs=d.getElementsByTagName(s)[0]; if(d.getElementById(id)) {return;} js = d.createElement(s); js.id = id; js.src = 'https://cdn.breadbutter.io/dist/breadbutter.3.0.0.142.min.js'; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'breadbutter-js')); </script> <script id="breadbutter-js" src="https://cdn.breadbutter.io/dist/breadbutter.3.0.0.142.min.js"></script> </head> <body></body> </html> Copy

Server Configuration

There are some implementation details required in order to retrieve the details of the users that are authenticating so that you can onboard them into your system’s workflows.
An APP_ID and APP_SECRET are required to authenticate your implementation with the Bread & Butter system. Additionally you must configure a CALLBACK_URL that points to a location in your system where you wish to handle authentications.

  • Retrieve your APP_ID and set up a CALLBACK_URL for your application via your App Settings configuration.
  • Configure an APP_SECRET for your application here.

Client Instantiation

PHP
1
2
3
4
5
6
7
8
9
10
<?php use BreadButter\API\BreadButterClient as BreadButterClient; $breadButterClient = new BreadButterClient(array( 'app_id' => '{APP_ID}', 'app_secret' => '{APP_SECRET}', 'api_path' => '{BreadButter_API_ENDPOINT}', )); Copy
1
2
3
4
5
6
7
using BreadButter; using BreadButter.Model; BreadButterClient client = new BreadButterClient("{APP_ID}", baseUrl: "{BREADBUTTER_API_ENDPOINT}", appSecret: "{APP_SECRET}"); Copy

Get Authentication

The following example demonstrates what to do once the Callback Url has been used by our system to redirect the user back to your page:

Java
1
2
3
4
5
6
7
8
9
<?php $token = $_REQUEST['token']; $loginData = $logonClient->validateLogin($token); if ($loginData['body']['event_success']) { //success! } Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
using LogonLabs; //NOTE: depending on what flavor of .NET you are using (Asp.Net Core, .NET Framework), this could be slightly different var token = Request.Query[Constants.QueryString.token]; ValidateLoginResponse response = client.validateLogin(token); if(response.event_success) { //authentication and validation succeeded. proceed with post-auth workflows (ie, create a user session token for your system). } Copy

API Resources

Authentication

The Bread & Butter API acts as a broker for identity providers. To initiate a login request you simply post to our authorization interface with the required information.

For GetAuthentication you need to pass your app_id and app_secret for authentication. These can be found at App Settings and App Secrets.

ErrorHandling

Bread & Butter uses HTTP response codes to indicate the success or failure of a request.

HTTP Status Descriptions
CodeMeaning
200 - OKAll good.
302 - RedirectUsed by the browser during the redirection workflows for authentication.
400 - Bad RequestBad request or invalid application configuration.
401 - UnauthorizedRequest not authorized.
404 - Not FoundCould not find requested resource.
500 - Internal Server ErrorError with the LogonLabs service.

Callback URL

After redirecting the user to the desired Identity Provider, the Callback URL is used to transfer control from BreadButter back to your system.

Once a user has authenticated with an Identity Provider, BreadButter will invoke your Callback URL with an ‘app_id’ and ‘token’ as query string parameters. Your system will need to implement code that gets the ‘authentication_token’ from the query string and then calls ‘GetAuthentciation’ to determine if the login attempt was a success. After checking the results of ‘GetAuthentication’, the normal user authentication workflow can resume (ie. creating the user’s session, creating cookies, redirecting to a default page, etc).

Client API

RegisterDevice

POST /devices

Provisions a new device for the front end. This get associated with the current user using the system and acts to track and link all actions performed by that user.

Response

device_id string
Unique identifier for an instance of your front end.
Example Java
                            {
 "device_id": "5fea69cda332541752dd12d6"
}
                        

GetClientSettings

GET /apps/{app_id}/client_settings

Request

app_id string
Unique identifier for your application.
device_id string
Unique identifier for an instance of your front end.
email_address string (optional)
Enables a more custom UI experience based off the context set by the email address.
Providers Request Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "device_id": "5fea650bb109764ea3dc56fd",
 "email_address": "username@yourdomain.com"
}
                        

Response

suggested_identity_provider object
The best matching provider available on the email_address passed in the request.
providers array
A list of all providers available to use for StartAuthentication.
[-] Show Child Properties
Provider
id string
The unique identifier for the provider.
name string
The name assigned to the provider during configuration.
idp string
Allowable values consist of google, microsoft, facebook, linkedin, slack, github, okta, quickbooks, onelogin, twitter, apple, basecamp, dropbox, fitbit, planning_center, twitch.
type string
Allowable values social and enterprise.
customization Provider[]
The UI customization configured for the provider.
settings object
Settings .
[-] Show Child Properties
ClientSettings
discovery_required boolean
This option controls if the JSL prompts the user for their email address before showing sign in options.
invite_required boolean
This option controls whether users require an invitation before authenticating with the application.
privacy_policy_url string
Url to your privacy policy.
terms_and_conditions_url string
Url to your terms and conditions.
password_settings UserPasswords
Password customization information so the JSL can help enforce password validation without having to make a request to the API.
user_profile object
The profile of the user linked with the email_address and/or the device_id.
[-] Show Child Properties
Provider
id string
The unique identifier for the provider.
name string
The name assigned to the provider during configuration.
idp string
Allowable values consist of google, microsoft, facebook, linkedin, slack, github, okta, quickbooks, onelogin, twitter, apple, basecamp, dropbox, fitbit, planning_center, twitch.
type string
Allowable values social and enterprise.
customization Provider[]
The UI customization configured for the provider.
GetClientSettings Response Java
                            {
 "suggested_identity_provider": {
  "id": "{provider_id}",
  "name": "Example Suggested Provider",
  "type": "social",
  "idp": "google",
  "customization": null
 },
 "providers": [
  {
   "id": "0b5f9f0f83164bd0b85c7949253e1b8a",
   "name": "Example Provider",
   "idp": "okta",
   "type": "enterprise",
   "customization": {
    "login_button_image_uri": "https://your-domain/button-image.png",
    "login_icon_image_uri": "https://your-domain/icon-image.ico",
    "login_background_hex_color": "#D33115",
    "login_text_hex_color": "#FFFFFF"
   }
  }
 ],
 "settings": [
  {
   "discover_required": true,
   "invite_required": false,
   "privacy_policy_url": "https://example.com/privacy-policy",
   "terms_and_conditions_url": "https://example.com/terms-and-conditions",
   "password_settings": {
    "enabled": true,
    "min_length": 8,
    "min_uppercase_chars": 1,
    "min_lowercase_chars": 0,
    "min_symbol_chars": 1,
    "min_numeric_chars": 1
   }
  }
 ],
 "user_profile": {
  "state": "verified",
  "email_address": "stevesmith@example.com",
  "first_name": "Steve",
  "last_name": "Smith",
  "profile_image_url": "https://url-to-idp-profile-image.com",
  "reset_required": false,
  "has_password": false,
  "invited": null,
  "pending_pin_confirmation": null
 }
}
                        

StartAuthentication

POST /apps/{app_id}/users/authentications

This request begins user authentication.
A token will be returned that is used to call Redirect Authentication unless the user is using password authentication and has not yet confirmed their email.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
device_id string
Unique identifier for an instance of your front end.
auth_type string
Indicates whether to use single sign-on or password auth. Allowable values are `sso` and `auth`.
email_address string
Required when auth_type is set to `auth`. Otherwise optionally sets the
provider object (optional)
The identity provider that the user is redirected to for authentication when auth_type is sso (either idp or id is required).
[-] Show Child Properties
AuthProvider
id string
The unique identifier for the provider.
idp string
Allowable values consist of google, microsoft, facebook, linkedin, slack, github, okta, quickbooks, onelogin, twitter, apple, basecamp, dropbox, fitbit, planning_center, twitch.
user object (optional)
The user details required when auth_type is auth (either idp or id is required).
[-] Show Child Properties
AuthUser
password string
The password used to authenticate the user.
first_name string (optional)
Sets the first name of the user. Used during first-time access only.
last_name string (optional)
Sets the last name of the user. Used during first-time access only.
pin string (optional)
Optionally allows a user to pass an email confirmation pin directly to skip confirmation. Applicable only during Invitation workflows.
options object (optional)
Optional parameters for the authentication. Typically used to support more advanced authentication workflows.
[-] Show Child Properties
AuthOptions
client_data string (optional)
Used to carry state information in your application. This string value (can be JSON) will be passed to the callback at the end of the authentication workflow.
callback_url string (optional)
Url that the BreadButter server should redirect back to after authentication. Must be whitelisted in App configuration.
destination_url string (optional)
Url that the user should be redirected to after the login has been validated. This is used primarily for mobile workflows.
force_reauthentication string (optional)
Indicates whether to force re-authentication for the user. By default this is set to `off`. Pass `attempt` to ask the Provider to prompt for re-authentication but continue if not possible. Pass `force` to have the login action fail if the Provider does not prompt. Supported providers include Microsoft, Okta, Dropbox, OneLogin, Fitbit, and Twitter. Visit https://logonlabs.com/articles/force-reauthentication for more information.
StartAuthentication Request Java
                            {
 "app_id": "6ba4da69b3394e78927758597dc4482b",
 "device_id": "5fea69cda332541752dd12d6",
 "auth_type": "sso",
 "email_address": "username@yourdomain.com",
 "provider": {
  "idp": "google",
  "id": "2aff4b25798b44f9b5c42007890f1e41"
 },
 "user": {
  "password": "password",
  "first_name": null,
  "last_name": null,
  "pin": null
 },
 "options": {
  "client_data": "{}",
  "callback_url": null,
  "destination_url": null,
  "force_reauthentication": null
 }
}
                        

Response

authentication_token string
Token used to start the redirection workflow.
pending_pin_confirmation boolean
Indicates whether the user still needs to confirm their email address before completing authentication.
StartAuthentication Response Java
                            {
 "authentication_token": "5ff83b359e0b958b0e530678",
 "pending_pin_confirmation": false
}
                        

RedirectAuthentication

GET /apps/{app_id}/authetications/{authentication_token}/redirect

This call returns a 302 Redirect to the chosen provider. When the user finishes entering authentication credentials they are redirected back to the callback url specified in your settings at https://app.logonlabs.com/app/#/app-settings. The callback url will have a token in the query string that is used to retrieve the login results via GetAuthentication.

Request

app_id string
Unique identifier for your application.
authentication_token string
Token returned by StartAuthentication response.
RedirectAuthentication Request Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "authentication_token": "5fea650bb109764ea3dc56fd"
}
                        

Create Event

POST /apps/{app_id}/events

This call allows the client to manually create events. Requires a device_id.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
type string
Designates the event type. Allowable values: custom and page_view.
device_id string
Unique identifier for an instance of your front end.
custom object
Details of the event when `type` is custom.
[-] Show Child Properties
CustomEvent
name string
The name for the custom event.
page_view object
Details of the event when `type` is page_view.
[+] Show Child Properties
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "type": "page_view",
 "device_id": "5fea6510a332541752dd12c3",
 "custom": {
  "name": "custom-name"
 },
 "page_view": {
  "url": "https://example.com"
 }
}
                        

Response

event_id string
Unique identifier for the event.
Example Java
                            {
 "event_id": "5fea69bfa332541752dd12d4"
}
                        

Confirm User

POST /apps/{app_id}/users/confirm

This call confirms a user’s email with the system.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
email_address string
The email address of the user.
device_id string
Unique identifier for an instance of your front end.
pin string
The unique key sent to the user’s inbox.
options object (optional)
Optional parameters for the confirm action. Typically used to support more advanced authentication workflows.
[-] Show Child Properties
AuthOptions
client_data string (optional)
Used to carry state information in your application. This string value (can be JSON) will be passed to the callback at the end of the authentication workflow.
callback_url string (optional)
Url that the BreadButter server should redirect back to after authentication. Must be whitelisted in App configuration.
destination_url string (optional)
Url that the user should be redirected to after the login has been validated. This is used primarily for mobile workflows.
force_reauthentication string (optional)
Indicates whether to force re-authentication for the user. By default this is set to `off`. Pass `attempt` to ask the Provider to prompt for re-authentication but continue if not possible. Pass `force` to have the login action fail if the Provider does not prompt. Supported providers include Microsoft, Okta, Dropbox, OneLogin, Fitbit, and Twitter. Visit https://logonlabs.com/articles/force-reauthentication for more information.
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "email_address": "username@yourdomain.com",
 "device_id": "5fea6510a332541752dd12c3",
 "pin": "1234",
 "options": {
  "client_data": "{}",
  "callback_url": null,
  "destination_url": null
 }
}
                        

Response

authentication_token string
Token used to start the redirection workflow.
Example Java
                            {
 "authentication_token": "5ff83b359e0b958b0e530678"
}
                        

ResetPassword

POST /apps/{app_id}/users/reset_password

Starts the reset password workflow by sending an email to the user’s inbox.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
email_address string
The email address of the user.
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "email_address": "username@yourdomain.com"
}
                        

ConfirmResetPassword

POST /apps/{app_id}/users/confirm_password

Confirms the reset password workflow and changes the user’s password to the one entered.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
email_address string
The email address of the user.
pin string
The unique key sent to the user’s inbox.
password string
The password to change to for the user.
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "email_address": "username@yourdomain.com",
 "pin": "1234",
 "password": "password"
}
                        

ResendConfirmationEmail

POST /apps/{app_id}/users/resend_confirmation

Resends a confirmation email to the user.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
email_address string
The email address of the user.
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "email_address": "username@yourdomain.com"
}
                        

Server API

Requests that are made from your server side. All require an app secret to call.

Headers
HeaderDescription
x-app-secretYour app secret (user's app_secrets can be found at https://app.breadbuter.io/app/#/app-secrets).

GetAuthentication

GET /apps/{app_id}/authentications/{authentication_token}

Returns the details of a login action. Requires your app secret.

Request

app_id string
Unique identifier for your application. Provided by LogonLabs.
authentication_token string
The unique identifier to retrieve the response data package. Found in the query string of the redirection url.
Example Java
                            {
 "app_id": "6ba4da69b3394e78927758597dc4482b",
 "authentication_token": "5fea650bb109764ea3dc56fc"
}
                        

Response

app_id string
Unique identifier for your application.
user_id string
Unique identifier for the authenticated user.
auth_success boolean
This confirms that authentication succeeded.
auth_error string
The reason the authentication failed.
auth_data object
This object contains the details of the user that authenticated.
[-] Show Child Properties
AuthData
email_address string
The email address of the user.
first_name string
The first name of the user.
last_name string
The last name of the user.
profile_image_url string
Url to the profile image for the user.
uid string
This is a unique identifier created by the Identity Provider for the user.
data object
This is the raw data returned by the Identity Provider.
oauth_tokens AuthorizationDataTokens
Authorization Data Tokens are used to make API requests on behalf of the user by the OAuth protocol. In order to enable this feature Return Authorization Data must be enabled for your Provider. For more information visit https://logonlabs.com/articles/refresh-tokens.
provider_data object
This object contains the data that was returned from the Identity Provider authentication.
[+] Show Child Properties
options object
This object contains the options configured when the authentication request was initiated.
[-] Show Child Properties
AuthOptions
client_data string (optional)
Used to carry state information in your application. This string value (can be JSON) will be passed to the callback at the end of the authentication workflow.
callback_url string (optional)
Url that the BreadButter server should redirect back to after authentication. Must be whitelisted in App configuration.
destination_url string (optional)
Url that the user should be redirected to after the login has been validated. This is used primarily for mobile workflows.
force_reauthentication string (optional)
Indicates whether to force re-authentication for the user. By default this is set to `off`. Pass `attempt` to ask the Provider to prompt for re-authentication but continue if not possible. Pass `force` to have the login action fail if the Provider does not prompt. Supported providers include Microsoft, Okta, Dropbox, OneLogin, Fitbit, and Twitter. Visit https://logonlabs.com/articles/force-reauthentication for more information.
Example Java
                            {
 "app_id": "6ba4da69b3394e78927758597dc4482b",
 "user_id": "5fea650bb109764ea3dc56fe",
 "auth_success": true,
 "auth_error": true,
 "auth_data": {
  "email_address": "",
  "first_name": "",
  "last_name": "",
  "profile_image_url": ""
 },
 "provider_data": {
  "provider": "google",
  "provider_id": null,
  "name": "",
  "type": "social",
  "protocol": "oauth",
  "uid": "{UID}",
  "data": {},
  "oauth_tokens": {
   "access_token": "{access-token}",
   "access_token_expires_in": 3600,
   "refresh_token": "{refresh-token}",
   "can_refresh_token": true,
   "can_revoke_token": false
  }
 },
 "options": {
  "client_data": "{}",
  "callback_url": null,
  "destination_url": null,
  "force_reauthentication": null
 }
}