🛒 Supported on all platforms
💳 Available on Plus and Enterprise plans
👤 Accessible to all roles
Smile has introduced API keys as a replacement for Private Keys when interacting with the Smile REST API. API keys offer more granular access control, are easier to rotate, and are the best way to securely interact with Smile's REST API + sync data into external systems.
This article explains everything you need to know about the differences, and describes how to migrate from using a Private Key to instead using one (or many) API keys in their place.
Key differences between Private Keys and API keys
The differences between Private Keys and API keys exist in four areas. That is, the granularity with which they grant access to resources, the process for rotating them, the quantity that each account can have, and what they start with. At a glance:
| 🔏 Privileges | 🔁 Rotation | 🧮 Quantity | 📝 Starts With |
Private Keys | All-access | Downtime required | 1 per account |
|
API keys | Scoped per-key | Zero-downtime rotation | Unlimited |
|
Privileges:
Private Keys have access to all resources within a given account.
An API key only has access to the resources it was specifically granted access to at the time it was created. This allows you control exactly what each key (or service you're giving the API key to) has access to, and ensure it never accesses data that it shouldn't.
Rotation:
Private Keys require downtown and manual assistance from Smile in order to rotate.
API keys can be rotated within Smile Admin with zero downtime. This allows you to easily (and rapidly) rotate keys when staff members leave or in the event that the key is ever compromised.
Quantity:
Each account has only one Private Key, which must be shared across all services that the account is integrated with.
Each account can have an unlimited number of API keys, allowing you to easily create and manage access for each service or system you want to sync to or integrate with.
Starts With:
All Private Keys will start with
int_orsk_.All API keys will start with
api_.
✅ Tip: If you need help convincing your boss to make the switch, we recommend saying, "API keys help us better protect our rewards data with industry-standard features like granular access control and zero-downtime key rotation, so it seems like a big win for security!"
How to determine if migration is needed
The easiest way to identify if you need to migrate from a Private Key to API keys is to check all of your systems and services that integrate with Smile. Sometimes providers mix and match terms, but if you had to copy and paste a "private key," "key," "API key," or "API token" into the service to make it work, then it might be using a Private Key.
To verify, you can look at the value of the key/token you copy & pasted:
If it starts with
int_orsk_, then it's a Private Key and needs to be migrated.If it starts with
api_, then it's already an API key and no action is needed!
💡 Important: Official Smile integrations (e.g. those listed on the Integrations page in Smile Admin) don't use your Private Key and do not require migration. Only integrations that asked you to manually copy and paste a key into their own interface may require migration.
⚠️ Warning: A Private Key must still be used to initialize Smile.js (Smile's JavaScript SDK). At this time, migration is only required for integrations or systems using a Private Key to interact with Smile's REST API.
Migrate from using a Private Key to API keys
Pre-requisites: Before completing this guide, you'll need to ensure the following.
Your account is on a plan that includes API access. The easiest way to confirm this is in Smile Admin, going to Settings > Developer Tools. If you see a card to Manage API keys and there is a button to generate a new API key, then you have access!
You have a full and complete list of any existing services or integrations currently using your Private Key (see above).
Migration steps: For each of the places/services where you're currently using a Private Key, follow these steps.
In Smile Admin, create a new API key specifically for the service.
Choose a name that represents what the key will be used for (e.g. "Data Warehouse Sync"), and grant only the access scopes required for performing the task the API key will perform.
If you're not sure what access scopes the service needs, confirm with your own team or the makers of the integration.
Copy the new API key from Smile and paste it into the service/place where you were previously using a Private Key.
Repeat these steps for every service where you're currently using a Private Key.
Once you've repeated the steps above for every place where you're currently using a Private Key, your migration is complete! Smile will announce an official end-of-life date for Private Keys sometime in the future and at that point the old Private Key will stop working without any action required on your part.
✅ Tip: After completing the migration, be sure that if any new services need access to your account data, you create a new API key for them (instead of giving them your legacy Private Key).