Skip to main content
Smile has introduced API keys as a replacement for Legacy 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 Legacy Private Key to instead using one (or many) API keys in their place.
Feature availability: API access is available on Plus and Enterprise plans.
Warning: Legacy Private Keys will stop working after January 31, 2026. Please ensure you complete the migration before this date.

​
Differences between Legacy Private Keys and API keys

The differences between Legacy 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
Legacy Private KeysAll-accessDowntime required1 per accountint_ or sk_
API keysScoped per-keyZero-downtime rotationUnlimitedapi_
Privileges:
  • Legacy 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:
  • Legacy 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 Legacy 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 Legacy Private Keys will start with int_ or sk_.
  • 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 where migration is needed

The easiest way to identify where you need to migrate from a Legacy Private Key to API keys is to check all of your systems and services that integrate with Smile. Commonly, this will include places like mobile app builders or email service providers. 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 if the service is using a Legacy Private Key, you can look at the value of the key/token you copy & pasted:
  • If it starts with int_ or sk_, then it’s a Legacy 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 Legacy 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.

​
Migrate from using a Legacy 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 Legacy Private Key (see above).
Migration steps: For each of the places/services where you’re currently using a Legacy Private Key, follow these steps to complete the migration without any downtime.
  1. In Smile Admin, create a new API key specifically for the service.
    1. 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.
    2. If you’re not sure what access scopes the service needs, confirm with your own team or the makers of the integration.
    3. FYI: Creating an API key will not cause your Legacy Private Key to stop working. This means the migration can happen without downtime!
  2. Copy the new API key from Smile and paste it into the service/place where you were previously using a Legacy Private Key.
  3. Repeat these steps for every service where you’re currently using a Legacy Private Key.
Once you’ve repeated the steps above for every place where you’re currently using a Legacy Private Key, your migration is complete! January 31, 2026 is the official end-of-life date for Legacy Private Keys, and after that time your Legacy Private Key will stop working without any action required on your part. Until then, both API keys and Legacy Private Keys will continue to function.
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).