Authenticate and authorize Chat apps and API requests

Developer Preview: Authenticating with user accounts is currently available as part of the Google Workspace Developer Preview Program, which grants early access to certain features. Authenticating with service accounts is generally available.

Authentication and authorization are mechanisms used to verify identity and access to resources, respectively. This document outlines how authentication and authorization work for Chat apps and Chat API requests.

Process overview

The following diagram shows the high-level steps of authentication and authorization for Google Chat:

Figure 1. High-level steps for Google Chat authentication and authorization

1. Configure a Google Cloud project, enable Chat API, and configure your Chat app: During development, you create a Google Cloud project. In the Google Cloud project, you enable Chat API, configure your Chat app, and set up authentication.

2. Call Chat API: When your app calls the Chat REST API⁠—which usually happens after a user in Google Chat invokes the app by messaging it, clicking a button on a card, or issuing a slash command⁠—it sends authentication credentials to Chat API. If your app authenticates with a service account, the credentials are sent as part of your app's code. If your app authenticates as a user, the user might receive a sign-in prompt.

3. Request resources: Your app asks for access with scopes that you specify while setting up authentication.

4. Ask for consent: If your app is authenticating as a user, Google displays an OAuth consent screen so the user can decide whether to grant your app access to the requested data. Authentication with a service account doesn't require user consent.

5. Send approved request for resources: If the user consents to the authorization scopes, your app bundles the credentials and the user-approved scopes into a request. The request is sent to the Google authorization server to obtain an access token.

6. Google returns an access token: The access token contains a list of granted scopes. If the returned list of scopes is more limited than the requested scopes, your app turns off any features limited by the token.

7. Access requested resources: Your app uses the access token from Google to invoke the Chat API and access Chat API resources.

8. Get a refresh token (optional): If your app needs to access the Google Chat API beyond the lifetime of a single access token, it can get a refresh token.

9. Request more resources: If your app needs more access, it asks the user to grant new scopes, resulting in a new request to get an access token (steps 3–6).

When Chat apps require authentication

Chat apps can message Google Chat synchronously or asynchronously. They can also complete tasks, like creating a Chat space, on a user's behalf.

Synchronous messages don't require authentication, unless the Chat app calls the Chat REST API or another Google API while processing a response.

To send asynchronous messages or work on a user's behalf, Chat apps make RESTful requests to the Chat REST API, which require authentication and authorization.

Synchronous messages don't require authentication

Synchronous messages are responses to Chat events. Google Chat apps are able to receive and respond to events after being configured and published on the Chat app configuration page, and do not require authentication or authorization.

Examples of synchronous Chat events include:

• A user sends a message to a Chat app in Google Chat.
• A user mentions a Chat app.
• A user invokes one of the Chat app's slash commands.

The following diagram shows a basic synchronous request-response sequence between a Chat user and Chat app:

Figure 2. Synchronous messages don't require authentication

1. The user sends a message to the Chat app in Google Chat.
2. Google Chat forwards the message to the app.
3. The app receives the message, processes it, and returns a response to Google Chat.
4. Google Chat renders the response for the user, or in a space.

This sequence repeats for each Chat event.

Asynchronous messages require authentication

Asynchronous messages occur when a Chat app makes a request to the Chat REST API, which requires authentication and authorization.

By calling the REST API, Chat apps can post messages to Google Chat or complete tasks and access data on a user's behalf. For example, after detecting a server outage, a Chat app can call the Chat API to:

• Create a Chat space dedicated to investigating and fixing the outage.
• Add people to the Chat space.
• Post a message to the Chat space to give details about the outage.

The following diagram shows a basic asynchronous message sequence between a Chat app and a Chat space:

Figure 3. Asynchronous messages require authentication

1. A Chat app creates a message by calling the Chat REST API using the spaces.messages.create method, and includes service account credentials in the HTTP request.
2. Google Chat authenticates the Chat app with service account or user credentials.
3. Google Chat renders the app's message to a specified Chat space.

Chat API scopes

To define the level of access granted to your app, you need to identify and declare authorization scopes. An authorization scope is an OAuth 2.0 URI string that contains the Google Workspace app name, what kind of data it accesses, and the level of access.

Google Chat supports the following scopes:

Google Chat API Scope	Description
https://www.googleapis.com/auth/chat.bot	Allows Chat apps to view chats and send messages. Note: The chat.bot scope: Only supports service accounts. You can't authenticate user credentials using this scope. Does not support domain-wide delegation.
https://www.googleapis.com/auth/chat.delete	Delete conversations and spaces & remove access to associated files in Google Chat.
Memberships
https://www.googleapis.com/auth/chat.memberships	View, add, and remove members from conversations in Google Chat.
https://www.googleapis.com/auth/chat.memberships.app	Lets the Chat app add and remove itself (but not other apps) to and from conversations in Google Chat.
Messages
https://www.googleapis.com/auth/chat.messages	Create, get, update, delete, and list messages in Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions	View, add, and delete reactions to messages in Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.create	Add reactions to messages in Google Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly	View reactions to messages in Google Chat.
https://www.googleapis.com/auth/chat.messages.readonly	Get and list messages in Google Chat.
Spaces
https://www.googleapis.com/auth/chat.spaces	Create conversations and spaces and view or update metadata (including history settings) in Google Chat.
https://www.googleapis.com/auth/chat.spaces.create	Create conversations in Google Chat.
https://www.googleapis.com/auth/chat.spaces.readonly	View chat and spaces in Google Chat.

To learn more about scopes for Google Workspace APIs, see How to choose scopes for your app.

For a list of available scopes, see OAuth 2.0 Scopes for Google APIs.

Types of required authentication

There are two ways Chat apps can authenticate and authorize with the Chat API: user credentials or service accounts.

With user credential authorization, a Chat app can access specified user data and complete specified actions on a user's behalf. The authorized data and actions are specified by scopes.

With service account authorization, a Chat app accesses the API as an app using service account credentials, or by impersonating a user through domain-wide delegation.

The following table lists common scenarios that Chat apps encounter, whether they require authentication, and if so, what kind:

Scenario		No authentication required	User authentication supported	Service account supported
Receive messages from:	Chat events — — Apps Script callbacks — — Google Cloud Pub/Sub — —
Respond to messages:	Synchronously, via a Chat event — — Synchronously, via an Apps Script callback return value — — Asynchronously, via the Chat REST API —
Send new messages:	With incoming webhooks — — With the Chat REST API —
Create a Chat space:	With the Chat REST API — Using domain-wide delegation
Add users and apps to a Chat space:	With the Chat REST API — Using domain-wide delegation

Related resources

• For an overview of authentication and authorization in Google Workspace, see Learn about authentication & authorization in Google Workspace for Developers.
• For an overview of authentication and authorization in Google Cloud, see Authentication overview in the Google Cloud documentation.
• To learn more about service accounts, see Service accounts in the Google Cloud Identity and Access Management (IAM) documentation.
• To learn more about how Google APIs leverage OAuth 2.0, see Using OAuth 2.0 to Access Google APIs in the Google Identity documentation.

Next step

Set up authentication and authorization with user credentials or a service account.