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 Sunshine Conversations 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
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 Sunshine Conversations authorization model.
Scope of access
The Sunshine Conversations 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 Sunshine Conversations API provide progressively greater access to data and platform capabilities. For instance, 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 Sunshine Conversations account and thus provide access to the data of each app associated with the account.
| Scope | Access Rights |
|---|---|
| appUser | A single user’s conversation records, linked third party clients, and profile metadata. Can only be used with the SDKs. |
| 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.
The scope is specified differently depending on the authentication method used, see the basic authentication and JWT guides for an explanation of each.