Skip to main content
This guide is for partners who currently integrate with Smile using merchant-created API keys and want to migrate to an OAuth app instead. It walks through what changes, how to migrate your code, and how to move your existing merchants over.

​
What changes

For your code, surprisingly little — and the experience for merchants gets much better. You still call the same Smile REST API: the same endpoints, the same requests, and the same responses. What changes is how merchants connect your app up front, and the Authorization header you send with each API call. At a glance, here’s why OAuth is better for developers and merchants alike:
🔑 API keys🔐 OAuth
Smile plan requiredPlus or EnterpriseAny paid plan
Setup experienceManual copy & pasteOne-click connect
Access scope selectionManual (error prone)Automatic
Adding access scopesRequires a new keyAdded anytime
Zero-downtime token rotation❌✅
Loyalty account creation via the API❌✅
Webhook access❌✅
In-app integration listing❌✅
Partner Portal access❌✅

​
Before you start

This guide assumes you have an app in the Partner Portal to configure during the migration. If you don’t have one yet, refer to our guide on building an app to get started. Before writing any code, it helps to take stock of your current integration:
  • Create a list of all the REST API endpoints your integration uses. For each one, take note of the required access scope, since you’ll need this to configure your OAuth app. The required scope for each endpoint is listed in the API Reference.

​
How to migrate

​
1. Get familiar with OAuth

OAuth apps use an OAuth 2.0 flow for granting your integration access to a Smile account. If you’re not already familiar with OAuth, we recommend reading our auth guide to get a sense for how this works before beginning the migration.

​
2. Configure your app

In the Partner Portal, open your app and configure its settings:
  • Add your Install URL and one or more Whitelisted Redirect URLs.
  • Confirm the Access scopes your app needs (based on the API endpoints you’re using).
  • Copy your Client ID and Client secret — you’ll need these for the OAuth flow.
Treat your Client secret like a password and store it only in secured backend code. If it’s ever exposed, you can rotate it with zero downtime.

​
3. Add a Connect Smile button

Swap the part of your merchant setup flow that asks for an API key with a Connect Smile button. When a merchant clicks it, redirect them to Smile’s authorization page, passing your Client ID and a state value you can verify later. After they approve the connection, Smile redirects them back to your redirect_uri with a temporary authorization code. Confirm the state matches the one you sent, then continue to the token exchange.

​
4. Exchange for an access token

Exchange the authorization code for an access token via a server-to-server request authenticated by your Client ID and Client secret. The response includes an access token, a refresh token, an expires_in lifetime, and the smile_account_id. For each merchant, securely store the access token, refresh token, token expiry (derived from expires_in), and smile_account_id. The smile_account_id identifies which Smile account the tokens belong to — store it alongside the merchant record that previously held their API key.

​
5. Update API call auth

Wherever your integration previously sent the merchant’s API key, send their OAuth access token instead. The request is otherwise unchanged:
cURL
curl https://api.smile.io/v1/customers \
  -H "Authorization: Bearer api_cnzGMghxTmPzK1sp"
  -H "Authorization: Bearer oa2_925f6e2f64f89bf4075bb8172c9a471f7f8b4e331bb7bf6d9c94a8029382cf45"

​
6. Refresh access tokens

Unlike API keys, OAuth access tokens expire — a request made with an expired token returns 401 Unauthorized. Store each access token’s expiry and, before it lapses, use the stored refresh token to request a new access token.

​
7. Use activities for actions

This step only applies if you currently use the create a points transaction endpoint. Smile offers two ways to issue points to customers, and the right approach depends on why you’re issuing points:
  • Points transactions directly add or remove points from a customer’s balance, like a ledger entry. Use these for adjustments that aren’t tied to a customer action — manual corrections, goodwill credits, or porting over an existing balance from a legacy system.
  • Activities tell Smile that a customer performed a rewardable action — like leaving a review or subscribing to a newsletter. Smile evaluates activities against the merchant’s configured ways to earn and issues the correct number of points automatically, without you needing to do any math or additional validation.
Points transactions aren’t going away. If you only ever adjusted balances directly and never issued points for a customer action, no changes are required.
If your integration used points transactions to reward customer actions, switch to using activities instead. Activities have a few benefits for merchants and customers:
  1. Merchants configure how many points customers will receive in Smile Admin, centralizing where loyalty program configuration is managed.
  2. Points issued via activities are correctly recorded and displayed within the merchant’s loyalty program analytics — making it easier for them to understand how customers are earning points.
  3. Customers will see how many points they’ll earn for performing an activity across all loyalty surfaces (like the rewards widget and Smile’s Loyalty Hub).
Activities issue a fixed number of points per action, set by the merchant’s ways to earn. If you need to award a variable amount based on a property of the action — like points per dollar on a scanned receipt — keep using a points transaction and calculate the amount yourself.
To migrate from using points transactions to activities:
1

Find your points transaction calls

Locate each place your integration calls POST /points_transactions. For each one, decide whether it rewards a customer action or just adjusts a balance — only action-based calls need to change.
2

Define an activity type

For each customer action, define a new activity type for your app in the Partner Portal. This is the action merchants build their ways to earn around.
3

Switch the API call

Replace the points transaction call with a create activity call, identifying the customer by Smile Customer ID or email. You no longer send a points amount — the merchant’s ways to earn determine the reward, and Smile issues it automatically once the activity is evaluated.
Creating an activity requires the activity:write scope, so confirm it’s included in your app’s access scopes (from step 2).

​
8. Test on a dev account

Once you’ve finished building, the next step is to verify the end-to-end flow on a development Smile account:
  • A merchant can connect your app through OAuth and land back in your app connected.
  • Your app exchanges the authorization code for an access token and stores it.
  • Your app refreshes an access token successfully.
  • Every Smile API endpoint your integration uses works with the granted scopes.
  • If applicable, activity behavior works end to end.
Only development accounts can install unreviewed apps. If you need additional Smile accounts for testing, reach out to your partner manager.

​
9. Submit for review

Once your app is built and tested, make sure it meets the app requirements and submit it for review through the Partner Portal. Refer to our submission and review guide for a full walkthrough of the process.

​
Migrate existing merchants

Merchants who already connected your integration with an API key can’t be automatically converted to OAuth — each one needs to re-connect your app using the OAuth flow. To move an existing merchant over:
  1. Prompt the merchant to connect your app via the Connect Smile flow.
  2. Once they’ve connected and you’ve stored their tokens, switch to using the OAuth access token for that merchant.
  3. Stop using their stored API key, and give them guidance on removing the old key from Smile if they’d like to.
Because the new OAuth flow can run alongside your existing API key integration, you can migrate merchants gradually rather than all at once.

​
Communicate the benefits

When you prompt a merchant to reconnect, it helps to explain what they get from switching. Lead with the benefits that apply to everyone, then add the ones specific to your integration:
  • More secure — OAuth uses scoped access tokens with zero-downtime token rotation instead of long-lived API keys, keeping the merchant’s data safe.
  • New features automatically — with OAuth, your integration can roll out new features without needing to ask merchants to regenerate and re-copy API keys, so they always get the latest functionality!
  • Better analytics (if you move to activities) — points issued via activities are recorded in the merchant’s loyalty program analytics and shown across all loyalty surfaces, like the rewards widget and Smile’s Loyalty Hub.
  • Faster updates (if you adopt webhooks) — your app can subscribe to webhooks instead of polling, so customer updates sync in near real time.

​
Migration checklist

Use this to track your migration:
  • I can explain what my current API key integration does.
  • I know which Smile API endpoints my integration calls.
  • I confirmed which OAuth access scopes my app needs.
  • I configured my app’s Install URL, Whitelisted Redirect URLs, and access scopes in the Partner Portal.
  • I added a Connect Smile button to my app.
  • A merchant can approve my app in Smile and return to my app connected.
  • My app exchanges the authorization code for an access token and stores it securely.
  • My app calls the Smile API with the OAuth access token.
  • My app refreshes the access token when it expires.
  • I moved any action-based points transactions to activities (if applicable).
  • My existing merchants know they need to reconnect once.
  • After a merchant reconnects, my app stops using their old API key.
  • I tested the full flow on a development Smile account.

​
Future considerations

You don’t need these to migrate, but they’re worth revisiting once your OAuth app is live.

​
Replace polling with webhooks

OAuth apps can subscribe to webhooks, so if your integration is currently polling for customer updates, this behavior can be replaced with a webhook subscription. There’s no need to rewrite your syncing logic as part of the migration though — you can adopt webhooks whenever it’s convenient.

​
Where to get help

If you have questions about the migration or your app setup, reach out to your partner manager or our support team. For a deeper look at the moving parts, see the OAuth flow, access scopes, and building an app guides.

​
FAQ

No. The endpoints, request formats, and responses are the same. The only change is the credential in the Authorization header — an OAuth access token (oa2_...) instead of an API key (api_...).
Yes. The OAuth install flow can run alongside your existing API key setup, so you can build and test OAuth, then move merchants over gradually rather than all at once. That said, we don’t recommend allowing both indefinitely as it will lead to difficulty with debugging and maintenance over time.
Nothing automatic. Once a merchant has connected via OAuth and you’ve stored their access token and refresh token, you should advise the merchant to delete the old API key in Smile — but until they do so, their API key will continue to function as normal.
Request the scopes that match what your API keys do today. Smile uses the same read/write scope model for both, and the required scope for each endpoint is listed in the API Reference. Refer to our access scopes guide for additional information on how this model works.