Overview

Authentication

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.

API Keys

An API key is composed of an id and a secret and is associated with one of the following entities:

  • App
  • User Account
  • Service Account

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.

Creating an App API Key

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.

App API key

API Libraries

API libraries simplify the interactions with the API. See their respective documentation for how to use basic authentication or JWTs to authenticate API requests.

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

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

The scope is specified differently depending on the authentication method used, see the basic authentication and JWT guides for an explanation of each.