Authorization

This section provides an overview of the Smooch authorization model.

Scope of access

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 (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.

ScopeAccess Rights
appUserA single user’s conversation records, linked third party clients, and profile metadata.
appAll of the users and conversations created within an app, as well as app configuration details including integrations and webhooks.
accountAll apps associated with the account.

Smooch API credentials come in the form of JWTs that have been signed by a secret key. For details on how to issue JWTs, please see the section regarding JWTs, and the REST API documentation.

Handle credentials with caution

Credentials issued with app and account scope are highly sensitive. They grant broad access to all users in your app or all apps under your account. If these credentials were to leak, the privacy and security of your users would be put at risk. You should therefore safeguard these credentials very carefully. You should only use app and account scoped credentials to make server-to-server API calls from a secure environment; they should never be served to a browser client, and they should never be used to call the Smooch API from browser code. To mitigate this risk, the Smooch API will not return CORS headers for app and account scoped credentials. Attempting to use such credentials from a browser will result in a same-origin policy browser error.

Serving appUser scoped JWTs to a browser however is a necessary part of authenticating users. Using appUser credentials to call the Smooch API from browser code is acceptable as long as its done as part of an authenticated user session. In other words, a user must prove their identity by some means (such as logging in, or presenting a valid session cookie) before your service issues them a JWT. To facilitate this use case, the Smooch API will return CORS headers for appUser scoped credentials.

Examples

The examples illustrated in most sections of this guide, and most of the work you perform using the Smooch API, will be performed with API tokens you create at app scope.

We recommend that you make use of the convenient API libraries when using the API. These libraries greatly simplify authentication and usage of the Smooch API by letting you focus on application logic instead of the details around authentication.

If you’d like to use the API directly, or want to learn how Smooch manages authentication at the API level, read the documentation on crafting JSON Web Tokens.