Introduction to Account Provisioning

The Smooch account provisioning APIs allow you to programmatically create apps on behalf of your customers, or to provide them with scoped credentials to manage their own set of apps. If you need to embed messaging capabilities in your software, and offer those capabilities to your different customers in an automated way, the account provisioning APIs are there to help you achieve that goal.

What can you build with the account provisioning API?

With the account provisioning API, you can provide messaging as a core feature of your software product - without necessarily revealing to your customers that you’re using Smooch to power delivery of those messages. This allows you to benefit from the power of Smooch to build innovative products and features. Here are some examples of how a few different types of software makers are using account provisioning today:

  • Help Desks can rapidly add support for a wide range of customer messaging channels.
  • Bot Platforms can instantly deploy bots across all messaging channels supported by Smooch.
  • Social Media Management Tools can move beyond publishing on feeds and expand to 1:1 conversations over messaging.
  • Call Center Software can securely add new channels at low cost to their offering.
  • Form & Survey Builders can move traditional web forms into more engaging conversational forms delivered across a range of channels.
  • Live Chat Software can add new messaging channels to their management software, allowing an agent to have conversations with more customers.

Introduction to Apps

An app represents a customer or business as a whole using your software, or a department within one of those customers or businesses. An app contains a set of configured channels as well as any associated appUser profile and conversation data. Each app’s appUser and conversation data exists separately; apps never share data between each other.

There are two typical ways to use the account provisioning API:

  1. For each customer or business using your software, you create a corresponding Smooch app. This will ensure that all their appUser data is grouped together, and is not shared with any of your other customers. You can optionally provide the customer with credentials that allow access to only their app (for example, to retrieve appUser or conversation history for import/export, or to add channels themselves) by generating and distributing app keys.
  2. As soon as a customer or business needs more than one app (for example, if they manage multiple brands, want to segment appUsers based on geographic location, across different products, etc.), you would create a separate app per set of appUsers. If the customer needs to manage these apps themselves, including creating new apps, then you can leverage service accounts to generate and distribute credentials scoped to their set of apps. This is also useful if you provide on-premise software that needs credentials to manage apps directly.

See creating and managing apps for more information.

Introduction to Service Accounts

A service account represents an API consumer, with its own set of credentials, that only has access to a certain subset of apps. For software makers that create apps on behalf of separate customers or businesses, service accounts can be used to generate and distribute credentials that only have access to a single business’ data.

For example, let’s say your company provides on-premise software, with no centralized cloud-based server. Your software, once deployed, allows a business to create as many Smooch apps as they want, in order to segment their appUsers based on some criteria (based on geographic location, across their different product offerings, per language, etc.).

In order to enable your deployment to authenticate with the Smooch API, you will need to distribute credentials to each of these on-premise deployments. But, you should not distribute a JWT signed with your user account keys, because that credential would allow separate deployments to manage each others’ data.

Instead, with your software you should:

  1. Create a service account for each on-premise deployment.
  2. Create and distribute service account credentials.

With these credentials, your customers will be able to call the Smooch API and create Smooch apps. Even though the apps ultimately exist under your Smooch user account, and fall under your own billing plan, each deployment would have access to manage their own apps, but are prevented from accessing those of other deployments.

See using service accounts for more information.


To get started with the account provisioning API, you’ll need to generate a User Account Secret Key and use it to authorize your calls to the API.

  • Generate the secret key from your Smooch account page.
  • See the authorization docs for instructions on how to generate an account scoped JWT.
  • See the API reference for account provisioning for the list of available API methods.

Pricing and Availability

You can use the account provisioning APIs on any pricing plan with API access. On certain plans, the number of apps you can create is capped, but you are still able to build, prototype and test your product.

If you’re building software on Smooch and want to create a number of apps, contact us to tell us about what you’re building and talk to sales about pricing options.