Using Service Accounts

Creating a Service Account

Service accounts can be created and managed with the Service Accounts API using a user account secret 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"}' \
  -H 'authorization: Bearer your-account-jwt'

Once the service account is created, you can create a secret key pair in order to sign JWTs for that service account.

curl https://api.smooch.io/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
  -X POST \
  -d '{"name": "My Key"}' \
  -H 'authorization: Bearer your-account-jwt'

When generating a JWT for a service account, the account scope is used. In addition to being able to create and manage apps, a service account credential can also be used with any API that allows app scope (provided the service account has access to the app in question), including fetching users, creating webhooks, sending messages, etc.

const jwt = require('jsonwebtoken');

const KEY_ID = 'svc_5808ba5cedf3b5931970e054';
const SECRET = 'TDCu5Y_ajUSHPfI-7nT3bzvZ';

const signJwt = function() {
    return jwt.sign({
        scope: 'account'
    },
    SECRET,
    {
        header: {
            kid: KEY_ID,
            typ: 'JWT',
            alg: 'HS256'
        }
    });
}

Alternatively, you can use the get service account JWT API to generate a service account JWT for a given secret key pair.

Managing Apps

Using a service account credential, you can create and manage apps on behalf of that service account. To create an app on behalf of service account, follow the normal app creation procedure, but supply a service account JWT in the Authorization header instead of a user account JWT. 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"}' \
  -H 'authorization: Bearer your-service-account-jwt'

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 Smooch 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 \
  -H 'authorization: Bearer your-service-account-jwt'

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 \
  -H 'authorization: Bearer your-account-jwt'

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 \
  -H 'authorization: Bearer your-service-account-jwt'

When the list of apps is empty, you can then delete the service account. Any secret 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 \
  -H 'authorization: Bearer your-account-jwt'