Home / DialogFlow / REST API / Understanding Dialogflow service account roles and their use cases
DialogFlow | REST API

Understanding Dialogflow service account roles and their use cases

As you try and use Dialogflow’s REST API, one of the things you will notice is that the documentation talks about “service accounts”.

In this article, we will see what these service accounts are and how they are typically used. Instead of going over any big theory (which is also important to fully master the REST API), I will just explain the basic use cases so you have a simpler starting point to understand how they work.

What are Dialogflow service accounts?

Simply put, a service account provides a way to call Google APIs from your code. Here is the official definition.

So we can use these service accounts to access your Dialogflow agent from your code.

How to create a service account for my Dialogflow agent?

Follow these steps

1 Go to your Dialogflow agent’s settings page. In the case of Dialogflow ES, you can just click on the name of the service account from the Settings page.

How to open the Google Cloud project associated with your Dialogflow agent

2 Once you are sure the correct Google cloud project has been selected, on the left hand side menu, go to APIs and Services > Credentials

How to go to the credentials screen

3 Create a suitable service account name and click the Create button

Provide details about your service account

4 Click into the Select a Role dropdown and type Dialogflow (to filter down the list)

Click into the dropdown box to filter down all the roles
Dialogflow related roles

5 Select the Dialogflow Service Agent role

Choose a role and click Continue

6 Click Done to create the Service account

No need to grant users access to this service account. Click Done.

7 You will be taken to the Credentials page. Now click on the Edit icon for the service account you just created.

Click on the Edit icon for the service account you just created

8 Click on the Add Key button at the bottom of the page

Add a Key for the selected service account

9 Select “Create new key” option

Click Create new key

10 In the popup, choose JSON (which is usually already selected) and click on the Create link.

Choose JSON key and click Create

This will create a JSON key and more importantly, you will now see that a file is being downloaded to your local computer. This is the client secret key JSON file that people refer to in most of the online documentation.

Rename the client secret file to something more human readable, and save it to your local computer to a directory you will remember.

How to use the client secret file for authentication inside your code

So the basic idea goes like this:

When you use a client library for Dialogflow, you will provide the name of the client secrets JSON file you saved to your local computer. The client library code will be able to read the information inside the client secrets JSON, and do some authentication magic behind the scene, and you will now be able to call your Dialogflow agent from your code.

Here is a very simple example:

from google.oauth2 import service_account
dialogflow_key = json.load(open('<service_account_path.json>'))
credentials = (service_account.Credentials.from_service_account_info(dialogflow_key))
session_client = dialogflow_v2.SessionsClient(credentials=credentials)

Notice that the second line uses a JSON file – that is basically the client secret JSON file that you just downloaded.

Use cases

So what are all those Dialogflow roles that you saw in the dropdown box? Let us go over them one by one with their associated use cases.

Dialogflow Service Agent

The Dialogflow Service agent role is the most common role you will be using, and it can be used for your typical integration scenario. You will add this to your custom integration code, and it will allow you to detect the intent for whatever your user types. This role has the least privilege amongst the Dialogflow service account roles.

Dialogflow API Client

This role has a few more permissions than the Service agent role. In addition to being able to detect the intent, you can also update the conversation context using this role.

Dialogflow API Reader

This roles allows you to read all the intents in a single Dialogflow agent.

Dialogflow Console Agent Editor

I haven’t had a chance to use this role. I believe it is used to provide a Google account (of say a team member) access to the agent inside the Dialogflow console.

Dialogflow API Admin

This is the role with maximum privilege, and allows you to get information about as well as update/modify/delete a single Dialogflow agent.

A service account can only be used with a single Dialogflow project

One of the important things to understand is that there is a one-to-one mapping between a service account and its corresponding project. So if you have built multiple Dialogflow agents, you need to create multiple service accounts for these agents. The exception is where you explicitly provide an already defined service account (from a different project) specific privileges to the current project, but that is a more complex scenario and beyond the scope of this article.


Related Posts