Smile.io

# Introduction

Welcome to Smile! Get familiar with the ways you can extend and integrate Smile.

### Questions

We're always happy to help with code or other questions you might have! Search our documentation at the top of the page, visit our [knowledge base](https://help.smile.io), or contact support through [support@smile.io](mailto:support@smile.io).


Introduction

Fundamentals

Use cases

Add Smile to any website

Landing/explainer page

# Rewarding for any action

{% hint style="info" %}
Only available on Enterprise plans.
{% endhint %}

Smile.io lets you reward for virtually any action your customers do while engaging with your brand. Our platform supports the ability to reward for a variety of standard actions, but sometimes you want to reward for additional custom actions that may be specific to your brand. Good news is, if your system is able to detect when the action occurs, then Smile can reward for it!

Here are some common custom actions we think are great candidates for rewarding:

* Newsletter subscription
* Blog post visit
* Watching a video
* Filling out a survey
* Voting on new product ideas

## How To: Reward for a newsletter subscriptions

### 1. Navigate to Settings > Developer Tools

![](../.gitbook/assets/developer-tools.png)

### 2. Click "Build my first custom activity"

![](<../.gitbook/assets/new-custom-activity (2).png>)

### 3. Fill out the name fields for the custom activity and save

![](../.gitbook/assets/name-custom-activity.png)

### 4. Notify Smile that the activity has occurred

After creating a new type of custom activity, you need to setup your system to notify us when the activity has occurred. You can do this via Javascript on the frontend, or server-side using an API call.

**Using Javascript**\
Copy the provided Javascript snippet into your frontend. We recommend inserting it as a callback (i.e. something that runs after submitting your newsletter subscription form or once the desired action has been completed).

![](../.gitbook/assets/js\_activity\_snippet.png)

{% hint style="warning" %}
**Be careful when using Javascript to send custom activities!**

Since Javascript source code is available in the web browser, users of your website can manipulate data via the Developer Console to send you multiple activities, or even activities that they have not actually performed. To eliminate this concern, consider [adding rate limits to your earning rules](https://help.smile.io/article/2449-limit-points-earning-for-certain-actions) (so that you only reward once for a given type of activity) or sending custom activities via a backend API call instead.
{% endhint %}

**Using a backend API call**\
You can use the Activities endpoint to notify Smile that a given activity has been performed by a customer. To do so, you'll need to extract the activity's token/type from the provided code sample:

![](../.gitbook/assets/code\_snippet.png)

The token/type will always start with `activity_`, followed by a series of letters and numbers. You will then use this value along with the customer's Smile ID to send an [API call to the activities endpoint](https://api-reference.smile.io/#create-an-activity) which lets us know the activity has taken place.

{% code title="POST https://api.smile.io/v1/activities" %}
```javascript
{
  "activity": {
    "customer_id": 1,
    "token": "activity_dDPUD2R6I9czhXcm037w6SWj"
  }
}
```
{% endcode %}

### **5. Setup an earning rule in your program to reward the custom activity**

By default, Smile does not issue rewards for new custom activities, so you need to [create a new earning rule](https://help.smile.io/article/2360-add-an-earning-action) that specifies how you would like to reward. When selecting what activity you would like to reward for, scroll to the bottom and choose the custom activity you just created.

![](../.gitbook/assets/choose\_earning\_action.png)

Once selected, you'll simply configure the earning rule as you would any other, and it will become available as part of your normal program!

{% hint style="info" %}
If you're notifying us that the activity has occurred using Javascript on the frontend, it's a good idea to make sure your earning rule has a [rate limit](https://help.smile.io/article/2449-limit-points-earning-for-certain-actions). This helps prevent abuse and spam from users playing around in their web browser's developer console.
{% endhint %}

## You have now created a custom activity!

That's it, you're done! Smile will now automatically issue rewards any time a customer performs the activity you've just setup.


Reward for any action

# Points spending at checkout

Allowing customers to redeem points at checkout is a great way to promote points spending and boost engagement with your reward program. Adding a points slider or dropdown to your checkout page makes spending points quick, easy, and seamless.‌

We've curated guides for each of our supported platforms with instructions on how to modify your checkout page.

## Shopify

* [Points dropdown at checkout](../install-smile/shopify/points-dropdown-at-checkout.md)
* [Points slider at checkout](../install-smile/shopify/points-slider-at-checkout.md)

## BigCommerce

* [Points dropdown at checkout](../install-smile/bigcommerce/points-dropdown-at-checkout.md)
* [Points slider at checkout](../install-smile/bigcommerce/points-slider-at-checkout.md)

## Custom platform

* [Points dropdown at checkout](../install-smile/custom-platform/frontend-integration/points-dropdown-at-checkout.md)


Points at checkout

Build an app

# Activities

Activities represent actions a customer may perform while interacting with an app. Using the activities API, an app is able to reward customers for any action.

### Creating a new activity type

Activity types can be created in the app settings page of the Partner Dashboard. Once an activity type has been created, you can use the provided token to create activities for customers in Smile.

Activity types map to actions that customers perform. For example, an activity type could be "Complete a survey". Then, whenever a customer completes a survey in your app, an activity could be sent to Smile.

### Creating an activity

In order to report actions that customers perform, you will need to create an activity in Smile via an API request. Take a look at our API reference for details on how to [create an activity](https://api-reference.smile.io/#create-an-activity).



Activities

Authorization

Submission process

# Webhooks

Instead of polling the Smile API for updates, your app can subscribe to webhook topics in order to receive events as they occur within Smile.

{% hint style="info" %}
**Webhooks must be used with HTTPS**. Webhooks are insecure if they are delivered without TLS. Only use HTTPS for your webhook URLs.&#x20;
{% endhint %}

### Creating a webhook

Webhooks can be created via the app settings page in the Smile Partner Dashboard.

Upon the creation of a Webhook, Smile will `POST` a test webhook to the supplied URL. This webhook will have the `ping` topic. In order for the webhook to be created, the endpoint must respond with a `2xx` HTTP status code. This is a simple smoke test that shows Smile your app is capable of receiving a webhook.

### Topics

Webhook topics allow an app to subscribe to specific events that occur in Smile. Below is a list of webhook topics that an app can subscribe to.

| Topic              | Description                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ping`             | This is a pseudo topic that gets sent by Smile to check if your webhook endpoint is functioning properly. The `data` portion of this webhook is an empty object. |
| `customer/updated` | Occurs when a customer is updated. This includes the initial creation of a customer.                                                                             |

### Structure

Webhooks have a consistent structure across all topics. They contain the following parameters.

| Parameter    | Description                                                                                                                               |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id` | The ID of the account on which the event occurred.                                                                                        |
| `data`       | The specific data pertaining to the webhook topic. For example, the data in a `customer/updated` webhook will contain a `customer`object. |
| `topic`      | The webhook topic. Topics contain two components: a subject and a verb separated by a slash (e.g. `customer/updated`).                    |

Here is an example webhook body.

```javascript
{
  "account_id": 0,
  "data": {},
  "topic": "ping"
}
```

#### Customer webhooks

For webhook topics with a "customer" subject (e.g. `customer/updated`), the data attribute in the webhook body will contain the following parameters.

| Parameter  | Description                                                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer` | An object representing the customer that was updated. See the [customer object](https://api-reference.smile.io/#the-customer-object) for the attributes that are included. |

### Verifying signatures

In order to verify that a webhook contains legitimate data, Smile signs the contents of each webhook with a `sha256` [HMAC](https://en.wikipedia.org/wiki/HMAC). Webhooks are signed using the app's client secret which can be found in the app settings page of the Smile Partner Dashboard.

The following headers must be utilized to verify the signature of a webhook.\


| Header            | Description                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Smile-Signature` | The HMAC generated by Smile. An app will attempt to compute this signature in order to verify that the webhook is legitimate. |
| `Smile-Timestamp` | The number of seconds since the Unix epoch (UTC). This value is used to prevent replay attacks.                               |

To verify a webhook's signature, the app must perform the following steps.

1. Concatenate the `Smile-Timestamp`, followed by a period (`.`), followed by the webhook request body.
2. Generate a `sha256` HMAC using the computed string and the app's client secret.
3. Compare the computed HMAC to the value of the `Smile-Signature`.
4. Verify that the timestamp is within 5 minutes of the current time.

For a working example, see the code snippet below.

{% tabs %}
{% tab title="Ruby" %}
```ruby
require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'


def verify_webhook_signature(body, timestamp, signature)
  client_secret = ENV['SMILE_CLIENT_SECRET']
  prepared_string = "#{timestamp}.#{body}"

  # Compute the hmac using the client secret.
  digest = OpenSSL::Digest.new('sha256')
  hmac = OpenSSL::HMAC.digest(digest, client_secret, prepared_string)
  encoded_hmac = Base64.encode64(hmac).strip

  # Verify that the webhook has been sent within the last 5 minutes.
  timestamp_plus_five_minutes = timestamp.to_i + 5 * 60
  webhook_is_fresh = timestamp_plus_five_minutes > Time.now.to_i

  # Check that the signature matches and the webhook is fresh.
  (encoded_hmac == signature) && webhook_is_fresh
end


post '/' do
  body = request.body.read
  timestamp = request.env['HTTP_SMILE_TIMESTAMP']
  signature = request.env['HTTP_SMILE_SIGNATURE']

  # Verify the webhook signature.
  verified = verify_webhook_signature(body, timestamp, signature)
  puts("Webhook verified: #{verified}")

  status 200
end
```
{% endtab %}

{% tab title="Python" %}
```python
import hmac
from base64 import b64encode
from hashlib import sha256
from os import environ
from time import gmtime
from flask import Flask, request, Response


app = Flask(__name__)


def verify_webhook_signature(body, timestamp, signature):
    client_secret = environ['SMILE_CLIENT_SECRET']
    prepared_string = '{timestamp}.{body}'.format(timestamp=timestamp, body=body)

    # Compute the hmac using the client secret.
    computed_hmac = hmac.new(client_secret, msg=prepared_string, digestmod=sha256)
    digest = computed_hmac.digest()
    encoded_digest = b64encode(digest)

    # Verify that the webhook has been sent within the last 5 minutes.
    timestamp_plus_five_minutes = int(timestamp) + 5 * 60
    webhook_is_fresh = gmtime(timestamp_plus_five_minutes) > gmtime()

    return (encoded_digest == signature) and webhook_is_fresh


@app.route('/', methods=['POST'])
def handler():
    body = request.get_data()
    timestamp = request.headers['Smile-Timestamp']
    signature = request.headers['Smile-Signature']

    # Verify the webhook signature.
    verified = verify_webhook_signature(body, timestamp, signature)
    print('Webhook verified: {verified}'.format(verified=verified))

    return Response(status=200)


app.run(port=4567)
```
{% endtab %}
{% endtabs %}

The above code snippet is functional, however in order to prevent timing attacks, a constant time string comparison function should be used when comparing signatures.

### Etiquette

Webhook processing should **not** be synchronous. When a webhook is received, it should be added to a queuing system for asynchronous processing. This frees up Smile's server resources. Apps that take a long time to respond to webhooks may have their webhooks disabled.

When responding to a webhook, the endpoint must use a `2xx` HTTP status code to indicate that the webhook was successfully received. Any status code outside of the `2xx` range will be considered a delivery failure.

### Retries

If a webhook fails to send for any reason, Smile will try to send the webhook again later. Smile uses an exponential back off algorithm when resending failed webhooks. If the webhook cannot be sent successfully within a 24 hour period, the webhook will be disabled for the entire app.

### Permissions

OAuth permissions determine if webhooks can be sent to an app for a given Smile account.

{% hint style="info" %}
**This section discusses OAuth concepts.** We suggest that you read the [Smile OAuth Reference](../oauth-reference/) before diving into this section.
{% endhint %}

Every webhook topic has corresponding OAuth permissions. For example, in order to receive `customer/updated` webhooks, the app must be granted the `customer:read` permission.

It is important to understand that app permissions are granted on a per-account basis. This means that an app is not guaranteed to have the same scope on all of the Smile accounts that it is installed on. As a result, an app will only receive webhooks for the subset of Smile accounts that have granted it one of the required permissions.

Once a webhook is created via the Smile Partner Dashboard and at least one user has authorized the app with one of the required permissions, the app will start to receive webhooks.


Webhooks

Deprecated

Custom HTML emails

Custom platform

Blank

Developer Docs

Guides and information on how to use Smile.io's developer resources and tooling.

Developer Docs | Smile.io

Production

Access scopes

App requirements

OAuth errors

OAuth flow

Client secret rotation

BigCommerce dropdown

BigCommerce slider

BigCommerce Stencil

Backend integration

Customer deleted

Customer events

Customer object

Customer updated

Example usage

Object reference

Handlebar variables

Frontend integration

Order deleted

Order events

Order object

Order updated

<p class="slate-p " >Integrating your product with Smile is easy and gives you access to an invite-only set of features for creating immersive and truly custom rewarding experiences.</p><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >Building an app is currently only available by special invitation. To inquire, visit <a href="http://smile.io/partners" target="_blank">smile.io/partners</a>.</p></div></div><div class="steps-widget" style="width:100%;
  	min-width:100%;"><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >1</h6><h3 class="slate-h3 " >Configure your app</h3><p class="slate-p " >After being invited to build an app, login to the <a href="https://partners.smile.io/" target="">Partner Portal</a> to create a new app and manage it&apos;s settings.</p></div></div><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >2</h6><h3 class="slate-h3 " >Setup OAuth</h3><p class="slate-p " >Allow merchants to install your app by connecting with Smile&apos;s <a href="66e875ec4d5db70fdbf4eec7/66e875ec4d5db70fdbf4eed3/66e875ec4d5db70fdbf4eed5" target="">OAuth flow</a>.</p></div></div><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >3</h6><h3 class="slate-h3 " >Build your features &amp; functionality</h3><p class="slate-p " >Follow our tutorials for building out the features and functionality of your app using <a href="66e875ec4d5db70fdbf4eec7/66e875ec4d5db70fdbf4eecf" target="">activities</a>, <a href="66e875ec4d5db70fdbf4eec7/66e875ec4d5db70fdbf4eed1" target="">webhooks</a>, and the <a href="https://dev.smile.io/api" target="">API Reference</a>.</p></div></div><div class="steps-wrapper"><div class="steps-content"><h6 class="slate-h6 " >4</h6><h3 class="slate-h3 " >Get your app launched</h3><p class="slate-p " >Once your app is built, ensure it meets all <a href="66e875ec4d5db70fdbf4eec7/69160877241290ce9a70c59c/691609b51acce2bbc0348f81" target="">app requirements</a> and then submit your app via the Partner Portal.</p></div></div></div><p class="slate-p " ></p><h2 class="slate-h2 " >Supported app types</h2><p class="slate-p " >At this time, Smile&apos;s app architecture is well-suited for apps that:</p><ol class="slate-ol " ><li class="slate-li " ><div style="position:relative">Issue rewards for customer actions that occur in external systems (like leaving a review)</div></li><li class="slate-li " ><div style="position:relative">Surface rewards information in external systems (like customer points balance)</div></li><li class="slate-li " ><div style="position:relative">Create loyalty accounts for customers</div></li></ol><p class="slate-p " >Refer to our <a href="https://dev.smile.io/api" target="">REST API Reference</a> for a full list of available endpoints.</p>

Integrating your product with Smile is easy and gives you access to an invite-only set of features for creating immersive and truly custom rewarding experiences.

At this time, Smile's app architecture is well-suited for apps that:

Integrate your product with Smile to make rewarding simple and easy.

# OAuth reference

OAuth allows you to connect Smile accounts to your application. This allows your application to write and read data in Smile on behalf of an account.

Before diving into the OAuth process, you may wish to brush up on [OAuth terminology](terminology.md).

{% hint style="info" %}
**OAuth must be used with HTTPS.** OAuth is insecure if it is performed without TLS. Only use HTTPS for your client redirect URIs.
{% endhint %}

## Step 1: Requesting authorization

The first step in the OAuth 2.0 protocol is for the client to request authorization from the user. This is done by redirecting the user agent to Smile's authorization page.

```ruby
GET https://connect.smile.io/oauth2/authorize
```

The following query parameters are permitted when redirecting a user agent to the authorization page.

| Parameter                 | Description                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`_required_     | The client's public ID. This can be found in your app settings in the Smile Partner Dashboard.                                                                                                                                                                                                                                         |
| `response_type`_required_ | The type of response you are requesting from the OAuth flow. This should always be `code`.                                                                                                                                                                                                                                             |
| `state` _optional_        | A value used by the client to maintain state between the request and callback. This value should be used to prevent cross-site request forgery.                                                                                                                                                                                        |
| `redirect_uri`_optional_  | The URI to redirect the user agent to once the OAuth flow has been completed. This must be one of the client's whitelisted redirect URIs. Redirect URIs can be viewed and modified via the app settings in the Smile Partner Dashboard. If a redirect URI is not explicitly provided, the first one in your app settings will be used. |
| `scope` _optional_        | A string representing the set of [permissions](permissions.md) to be requested from the user. If this parameter is not provided, Smile will use the client's scope.                                                                                                                                                                    |

## Step 2: Getting an access grant

After a user has approved or denied authorization for your application on Smile, their user agent will be redirected back to one of the client's whitelisted redirect URIs. If a redirect URI was provided during the authorization request, the user agent will be redirect there. Otherwise, they will be redirected to the first redirect URI under the client's app settings in the Smile Partner Dashboard.

### Handling a successful authorization attempt

After a user authorizes the client to act on behalf of their account on Smile, they will be redirected with the following query parameters.

| Parameter | Description                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| `code`    | A temporary code corresponding to an access grant. This code can be exchanged exactly once for an access token. |
| `state`   | The value of the state parameter that was provided in the authorization request.                                |

The `code` parameter can be exchanged for an access token. This process is outline in Step 3.

### Handling an unsuccessful authorization attempt

If the user denies the client permission to act on behalf of their account, or if the authorization request was malformed in some way, the user agent will still be redirected. However, there will be an `error` query parameter present that indicates what went wrong during the authorization request.

The client must gracefully handle these erroneous redirects. See the [OAuth errors](errors.md) section for more details and a full list of possible error states.

## Step 3: Exchanging an access grant for an access token

After a user authorizes a client to act on behalf of their Smile account, their user agent is redirected to the client's redirect URI with a `code` parameter. The value of the `code` parameter corresponds to an access grant. In this step, the access grant is exchanged for an access token.

### Making the request

To exchange an access grant for an access token, a server-to-server request must be made. The request must be made using [Basic HTTP Authentication](https://tools.ietf.org/html/rfc2617#section-2) with the client ID as the user-ID and the client secret as the password. The client ID and secret can be found in the app settings page in the Smile Partner Dashboard.

```ruby
POST https://connect.smile.io/oauth2/token
```

The following body parameters are permitted when exchanging an access grant for an access token.

| Parameter | Description |
| --------- | ----------- |

| <p><code>grant_type</code></p><p><em>required</em></p> | When exchanging an access grant for an access token, this value should be `authorization_code`. |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |

| <p><code>code</code></p><p><em>required</em></p> | The code received after the user agent successfully authorized the client. This code corresponds to an access grant in Smile. |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |

| <p><code>redirect_uri</code></p><p><em>conditional</em></p> | If a redirect URI was explicitly provided when requesting authorization, that same redirect URI must be present when exchanging the access grant for the access token. |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| <p><code>scope</code></p><p><em>optional</em></p> | A string of space-separated [permissions](permissions.md). This can be used to further restrict the scope that was authorized by the user. |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |

The token exchange request will respond with a JSON payload that contains the following parameters.

| Parameter          | Description                                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`     | The access token. This can be used to make authorized requests to Smile on behalf of a Smile account.                                                                                         |
| `token_type`       | The type of authentication token. This will be `bearer`.                                                                                                                                      |
| `expires_in`       | The number of seconds until the access token expires.                                                                                                                                         |
| `refresh_token`    | A refresh token that can be used to get a fresh access token when an old one expires.                                                                                                         |
| `scope`            | A space-delimited string containing the [permissions](permissions.md) that the client was granted. This describes which resources the client is permitted access with the given access token. |
| `smile_account_id` | The Smile account ID for the user that authorized the client.                                                                                                                                 |

Here is an example response.

```http
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "example",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "activity:write customer:read",
  "smile_account_id": 1
}
```

## Step 4: Using the access token

The access token received during Step 3 allows the client to make authorized requests to Smile on behalf of the user that authenticated the client.

In order to make an authorized request to Smile, include the access token in the `Authorization` header of a given request. Note that when using the access token, the authorization type is "Bearer". This corresponds to the `token_type` from the response in Step 3.

For example, to retrieve a list of customers on behalf of an account, the following request could be made.

```bash
curl https://api.smile.io/v1/customers \
  -H "Authorization:Bearer 2YotnFZFEjr1zCsicMWpAA"
```

## Step 5: Refreshing an access token

If a request is made with an expired access token, the client will receive a `401 Unauthorized`\
response. When this happens, the client can use a refresh token to obtain a new access token.

Access tokens always have an expiration. We suggest the following pattern for determining when you should refresh your access token.

* Upon receiving the access token, store the time at which it will expire using the `expires_in` attribute
* Before making a request, if the time the token is expected to expire at is within five minutes of the current time, refresh the token

### Making the request

When refreshing an access token, the request must be made using [Basic HTTP Authentication](https://tools.ietf.org/html/rfc2617#section-2) with the client ID as the user-ID and the client secret as the password. The client ID and secret can be found in the app settings page in the Smile Partner Dashboard.

```ruby
POST https://connect.smile.io/oauth2/token
```

The following parameters are permitted when refreshing an access token.

| Parameter | Description |
| --------- | ----------- |

| <p><code>grant_type</code></p><p><em>required</em></p> | When refreshing an access token, this value should be `refresh_token`. |
| ------------------------------------------------------ | ---------------------------------------------------------------------- |

| <p><code>refresh_token</code></p><p><em>required</em></p> | The refresh token to use in order to obtain a new access token. |
| --------------------------------------------------------- | --------------------------------------------------------------- |

| <p><code>scope</code></p><p><em>optional</em></p> | A string of space-separated permissions. This can be used to further restrict the scope of the access token that is being refreshed. |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |

The token refresh request will respond with a JSON payload that contains the following values.

| Parameter          | Description                                                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `access_token`     | The access token. This can be used to make authorized requests to Smile on behalf of a Smile account.                                                                                            |
| `token_type`       | The type of authentication token. This will be `bearer`.                                                                                                                                         |
| `expires_in`       | The number of seconds until the access token expires.                                                                                                                                            |
| `refresh_token`    | A refresh token that can be used to get a fresh access token when an old one expires. This will be the same refresh token that was used to make the request.                                     |
| `scope`            | A space-delimited string containing the [permissions](permissions.md) that the client was granted. This describes which resources the client is permitted to access with the given access token. |
| `smile_account_id` | The Smile account ID for the user that authorized the client.                                                                                                                                    |

Here is an example response.

```http
HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
Content-Type: application/json

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "example",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "activity:write customer:read",
  "smile_account_id": 1
}
```


# Errors

Errors encountered during the OAuth process conform to the [OAuth2 error spec](https://tools.ietf.org/html/rfc6749#section-4.1.2.1). As a result, they have a slightly different format than the error object [Smile typically uses](https://api-reference.smile.io/#errors).

OAuth errors will always contain an `error` key. They will also contain a `state` key if any state was provided by the client during the request.

If an error is encountered during the authorization phase of the OAuth flow, the user agent will be sent to the appropriate redirect URL with an `error` query parameter (as well as a `state` query parameter if state was provided). If an error is encountered during the token exchange phase, it will be presented as an object in the request response. See the snippet below for an example.

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_grant"
}
```

The OAuth spec defines a set of errors that should be used in various erroneous scenarios. See the following reference table for a complete list of OAuth errors.

| Error                       | Description                                                                                                                                                                                                                                                           |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied`             | The resource owner or authorization server denied the request.                                                                                                                                                                                                        |
| `invalid_grant`             | The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.                         |
| `invalid_request`           | The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.                                                                                                                     |
| `invalid_scope`             | The requested scope is invalid, unknown, or malformed.                                                                                                                                                                                                                |
| `server_error`              | The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)                   |
| `temporarily_unavailable`   | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.) |
| `unauthorized_client`       | The client is not authorized to request an authorization code using this method.                                                                                                                                                                                      |
| `unsupported_response_type` | The authorization server does not support obtaining an authorization code using this method.                                                                                                                                                                          |



# Permissions

Permissions dictate which resources an entity has access to, as well as which operations an entity can perform. Smile splits permissions into two main types: read and write.

Traditionally, "read" operations include HTTP `GET` requests, as well as subscribing to webhooks. Meanwhile, "write" operations typically include HTTP `POST`, `PUT`, and `DELETE` requests in addition to all the "read" operations. This means that a given "write" permission is always a superset of the corresponding "read" permission.

## Understanding scope

OAuth uses the concept of scopes to manage permissions for a client. A scope is simply a set of permissions. Both the client and individual access tokens have their own scopes.

### Client scope

The scope associated with a client represents the maximum set of permissions that a client can request authorization for from a user. This can be controlled via your app settings in the Partner Dashboard.

### Access token scope

The scope associated with an access token denotes the set of permissions that were granted to the client by the user. Since OAuth is not "all-or-nothing" authorization, it is possible for an access token to have a scope that contains only a subset of the permissions that were requested by the client.

## Available permissions

The set of permissions that your app can request can be modified in the app settings page of the [Partner Dashboard](https://partners.smile.io). The permissions selected there make up the client scope of your app. See the table below for a full list of the OAuth permissions that Smile currently provides.

| Permission       | Description                               |
| ---------------- | ----------------------------------------- |
| `activity:write` | Create activities on behalf of customers. |
| `customer:read`  | Read customer information.                |

## Adding permissions

As you develop your Smile app, you may wish to add more functionality. The app settings page in the [Partner Dashboard](https://partners.smile.io) allows you to do just that by adding new permissions to your app. This effectively increases the client scope.

When you add new permissions, your existing users will need to be directed back through the OAuth flow in order to grant your app the additional permissions that it now requires. It's up to you to notify your users when you want them to reauthorize your application.

To help with this, the [Smile Admin](https://app.smile.io) will automatically give users the ability to reauthorize the app if their access token scope differs from the client scope.

### Effect on webhooks

Your app may subscribe to webhook topics via the app settings page in the Partner Dashboard. An app will only start to receive webhooks for a given topic when users grant the required permission for that topic.

For example, let's pretend your application did not have the `customer:read` permission but you would like to add the `customer/updated` webhook. In order to do this, you would:

1. Select the `customer/updated` webhook topic in your app settings
2. Add the `customer:read` permission to your app
3. Prompt users to reauthorize your app

As users reauthorize and grant the `customer:read` permission, your app will dynamically start to receive `customer/updated`webhooks for those accounts.


# Client secret rotation

In the event that you feel your app client secret has been compromised, you should immediately rotate it out. Smile makes it possible for your app to rotate its Smile secret key with zero downtime.

## Step 1: Generate a new client secret

Generating a new client secret will allow you to start using it for authentication in the OAuth flow. Go to your app in the Partner Dashboard and click on "Generate new secret" under the App Information tab.

![](../../../.gitbook/assets/generate\_new\_secret.png)

After clicking "Generate new secret", you will see that there is now a "Secondary Client Secret" field.

![](../../../.gitbook/assets/secondary\_secret.png)

## Step 2: Use the secondary secret for OAuth

After generating the secondary secret, both the primary and secondary secrets can be used to acquire access tokens. Change your application to use the secondary secret.

## Step 3: Use the secondary secret to verify webhooks

Webhooks are always signed with the primary secret. Once we revoke the compromised primary secret, the secondary secret will automatically be promoted. Configure your application to accept webhooks signed with either the primary or the secondary secret.

## Step 4: Revoke the compromised secret

Press the delete Icon next to the compromised primary secret. This will remove it and promote the secondary secret. Any access tokens that were generated using the revoked secret will still be valid until they expire.

![](../../../.gitbook/assets/remove\_compromised\_secret.png)

## Step 5: Stop verifying webhooks with the compromised secret

You can now cleanup your code base to stop verifying webhooks with the compromised secret.

Voilà! Zero downtime client secret rotation 💪


Sections

Ask an AI

Code with AI