Client API

Last updated 01/06/2023

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": [
  {
   "discovery_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}/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 Bread & Butter.
device_id string
Unique identifier for an instance of your front end.
auth_type string
Indicates whether to use single sign-on, magic link auth, or password auth. Allowable values are `sso`, `magic_link` and `auth`.
email_address string
Required when auth_type is set to `auth`. Otherwise optionally sets the email address.
page_view_id string (optional)
Specifies the page that the custom event occurred on. Use the event_id returned from creating the last page view event.
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. Use this for Enterprise.
idp string
Allowable values consist of google, microsoft, facebook, linkedin, slack, github, okta, quickbooks, onelogin, twitter, apple, basecamp, dropbox, fitbit, planning_center, twitch. Use this for social.
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.
success_event_code string (optional)
Custom API Event that will be created when authentication is successful.
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://breadbutter.io/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.breadbutter.io/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 Bread & Butter.
device_id string
Unique identifier for an instance of your front end.
code string
Designates the event code, either page_view or customer defined event code.
data object (optional)
Details of the event when ‘code’ is page_view.
[-] Show Child Properties
URL Data
title string (optional)
Title of the website.
url string (optional)
The website URL. Supports UTM and gclid data.
ga_data object (optional)
Google analytics data, including cid.
page_view_id string (optional)
Specifies the page that the custom event occurred on. Use the event_id returned from creating the last page view event.
referrer_url string (optional)
URL of the page that the user came from before the current page. Used only for page_view events.
Example (page_view) Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "code": "page_view",
 "device_id": "5fea6510a332541752dd12c3",
 "data": {
   "title": "Homepage"
   "url": "https://example.com"
   "ga_data": {
     "cid": "GA1.1.173570127.1634663762"
   },
 },
 "referrer_url": "https://google.com"
}
                        
Example (custom API Event) Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "code": "contact_us",
 "device_id": "5fea6510a332541752dd12c3",
 "page_view_id": "5fea69bfa332541752dd12d4"
}
                        

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 Bread & Butter.
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://breadbutter.io/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 Bread & Butter.
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 Bread & Butter.
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 Bread & Butter.
email_address string
The email address of the user.
Example Java
                            {
 "app_id": "7951742f4c244baa9c03aa53921f8cf4",
 "email_address": "username@yourdomain.com"
}