Using Service Accounts

Creating a Service Account

Service accounts can be created and managed with the Service Accounts API using a user account API key. A service account must be given a unique name to identify the account.

curl https://api.smooch.io/v1.1/serviceaccounts \
  -X POST \
  -d '{"name": "My Service Account"}' \
  --user 'keyId:keySecret'

Generating Service Account Credentials

Once the service account is created, you can create an API key using a user account API key in order to generate credentials.

curl https://api.smooch.io/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
  -X POST \
  -d '{"name": "My Key"}' \
  --user 'keyId:keySecret'

The returned API key can be used to authenticate requests as a service account.

Service account credentials can be used to

  • create and manage apps
  • access data associated to apps it has access to, including fetching users, creating webhooks, sending messages, etc.

Managing Apps

Using a service account API key, you can create and manage apps on behalf of that service account. To create an app on behalf of a service account, follow the normal app creation procedure, but supply a service account API key instead of a user account API key. A service account is automatically granted access to any apps it creates.

curl https://api.smooch.io/v1.1/apps \
  -X POST \
  -d '{"name": "My App"}' \
  --user 'keyId:keySecret'

A service account will only be able to see apps it has access to. When listing apps, the returned list will include only those which the service account can access. When attempting to retrieve or modify an app that the service account does not have access to, a 404 Not Found status will be returned.

See creating and managing apps for more information on how to manage apps using the Sunshine Conversations API.

De-provisioning a Service Account

In the case where you have a customer that you no longer want to support, or has churned, it may be useful to de-provision the service account that was created for them, as well as any apps they have access to. This section describes how to delete a service account and its associated apps.

A service account can only be deleted if it no longer has access to any apps. That means, in order to delete a service account, you must first delete its apps. To get the list of apps that a service account has access to, you can either use the service account credential with the list apps API:

curl https://api.smooch.io/v1.1/apps \
  --user 'keyId:keySecret'

Or, you can use your user account credential and specify a serviceAccountId query parameter to list the apps for a given service account:

curl https://api.smooch.io/v1.1/apps?serviceAccountId=5a71d7419b3ad47012a5dde2 \
  --user 'keyId:keySecret'

Once you have the list of apps, you can use the delete app API to delete them one by one.

curl https://api.smooch.io/v1.1/apps/55c8d9758590aa1900b9b9f6 \
  -X DELETE \
  --user 'keyId:keySecret'

When the list of apps is empty, you can then delete the service account. Any API keys that exist for the service account will also be revoked in the process.

curl https://api.smooch.io/v1.1/serviceaccouts/5a71d7419b3ad47012a5dde2 \
  -X DELETE \
  --user 'keyId:keySecret'