When making API requests, authentication is required in order to verify the identity of the caller.
The identity can be provided by using either Basic Authentication or JSON Web Tokens (JWTs). While basic authentication is recommended in most cases, JWTs are still useful to expire credentials or to identify users in SDKs (see When to use JWTs? for more details).
Both authentication methods necessitate an API key.
An API key is composed of an id and a secret and is associated with one of the following entities:
Typically, an app API key is used to make requests to the API. See below for instructions on how to generate this type of API key. The two other types are useful in account provisioning use-cases.
From the Smooch dashboard, select your app and then select the settings tab. As you can see in the screenshot, the id and a secret are provided after creating an API Key.
API libraries simplify the interactions with the API. See their respective documentation for how to use basic authentication or JWTs to authenticate API requests.
This section provides an overview of the Smooch authorization model.
The Smooch API provides granular access control capabilities that help keep user data, configuration settings and conversations secure. This is accomplished through the use of scoped API access tokens, using basic authentication or JWTs, that can only access a limited set of data and APIs.
The scopes available in the Smooch API provide progressively greater access to data and platform capabilities. For instance, appUser scoped tokens operate only within the context of a particular user, app tokens operate within the context of a particular app and thus all of the users, conversations and configuration of that particular app, while account tokens operate within the context of a Smooch account and thus provide access to the data of each app associated with the account.
|appUser||A single user’s conversation records, linked third party clients, and profile metadata.|
|app||All of the users and conversations created within an app, as well as app configuration details including integrations and webhooks.|
|account||All apps associated with the account. Used in account provisioning use cases. See the account provisioning section on how to use this scope of access.|
Make sure to follow good practices to securely handle credentials when using an API key in production.