Secure Credential Handling

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.

Serving credentials to a browser or mobile application

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 mobile app or a browser.

Serving appUser scoped JWTs to a browser or a mobile application 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.

To mitigate risks in a browser environment, 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.

Rotating credentials

Rotating credentials is sometimes desirable in cases of a breanch or as a regular rotation process. However, specific steps need to be followed in order to avoid downtime.

Step 1. Add a new API key

If you wish to rotate credentials associated to an app, API keys are created with the dashboard.

If you are using Smooch in an account provisioning use case:

Step 2. Update the API key in your production environment

Make sure that your service uses the new API key.

Step 3. Monitor your service

Make sure everything is running smoothly.

Step 4. Remove the old API key

In most cases, this can be done via the dashboard.

If you are using Smooch in an account provisioning use case:

Expiring credentials

Time-based expiration

The easiest way to implement credential expiration is to share credentials as JWTs and set an exp property to the JWT payload (see Time-based expiration of credentials).

Manual expiration

JWTs only support time-based expiration. Expiring credentials manually is possible with basic authentication and JWTs by deleting an API key. Deleting an API key will invalidate all JWTs signed with that API key and will cause all requests using basic authentication with that API key to be rejected.

To delete an API key from the dashboard, use the “settings” tab in an app or the account “settings”.

To delete an API key from the API, you can use the Delete App Key API or the Delete Service Account Key API. User account API keys cannot be deleted from the API.