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:
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. For more information, see Develop on Google Workspace and Build a Chat app.
Call Chat API: When your app calls the Chat API, it sends authentication credentials to the Chat API. If your app authenticates with a service account, the credentials are sent as part of your app's code. If your app requires calling Chat API using a user's authentication that hasn't yet been granted, it prompts the user to sign in.
Request resources: Your app asks for access with scopes that you specify while setting up authentication.
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.
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.
Google returns an access token: The access token contains a list of granted scopes. If the returned list of scopes is more restrictive than the requested scopes, your app turns off any features limited by the token.
Access requested resources: Your app uses the access token from Google to invoke the Chat API and access Chat API resources.
Get a refresh token (optional): If your app must access the Google Chat API beyond the lifetime of a single access token, it can get a refresh token. For more information, see Use OAuth 2.0 to access Google APIs.
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 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 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 don't require authentication or authorization.
Examples of synchronous Chat events include the following:
- 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 synchronous request-response sequence between a Chat user and Chat app:
- The user sends a message to the Chat app in Google Chat.
- Google Chat forwards the message to the app.
- The app receives the message, processes it, and returns a response to Google Chat.
- 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 API, which requires authentication and authorization.
By calling the Chat 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 an asynchronous message sequence between a Chat app and a Chat space:
- A Chat app creates a message by calling the
Chat API using the
spaces.messages.create method, and includes user credentials in the HTTP request. - Google Chat authenticates the Chat app with service account or user credentials.
- 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
|
Lets Chat apps view chats and send messages. Gives access to all features available to Chat apps. |
https://www.googleapis.com/auth/chat.delete
|
Delete conversations and spaces, and 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. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Get details about a membership and list memberships in a space. |
| 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.create
|
Create messages and upload attachments 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 user data and complete actions on a user's behalf. OAuth scopes specify the authorized data and actions. However, these Chat apps can't be published publicly. For more information, see Publish Google Chat apps.
With app authorization, a Chat app accesses
the API as an app using service account credentials. App authorization always
uses the chat.bot authorization scope.
If you're a domain administrator, you can grant domain-wide delegation of authority to authorize an application's service account to access your users' data without requiring each user to give consent. After you configure domain-wide delegation, you can make API calls using your service account to impersonate a user account. Although a service account is used for authentication, domain-wide delegation impersonates a user and is therefore considered user authentication. Any functionality that requires user authentication, can use domain-wide delegation.
When deciding which type of credential to use for a particular API request, keep in mind that some API methods only support a particular type of credential. If an API method supports both credentials, the type of credential used in the call affects the result that is returned:
- With app authorization, the methods only return resources that the app can access.
- With user authorization, the methods only return resources that the user can access in the Chat UI.
For example, calling the ListSpaces method with app authorization returns the
list of spaces that the app is a member of. Calling the ListSpaces with user
authorization returns the list of spaces that the user is a member of. In
practice, your app might use both types of authorization when calling the
Chat API, depending on the functionality that you want.
For asynchronous Chat API calls
The following table lists the Chat API methods and their supported authorization scopes:
| Method | User authentication supported | App authentication supported | Authorization scopes supported | |
|---|---|---|---|---|
| Spaces | ||||
| Create a space | — |
|
||
| Set up a space | — |
|
||
| Get a space |
With User authentication:
|
|||
| List spaces |
With User authentication:
|
|||
| Update a space | — |
|
||
| Delete a space | — |
|
||
| Find a direct message |
With User authentication:
|
|||
| Members | ||||
| Create a member | — |
|
||
| Get a member |
With User authentication:
|
|||
| List members |
With User authentication:
|
|||
| Delete a member | — |
|
||
| Messages | ||||
| Create a message |
With User authentication:
|
|||
| Get a message |
With User authentication:
|
|||
| List messages | — |
|
||
| Update a message |
With User authentication:
|
|||
| Delete a message |
With User authentication:
|
|||
| Reactions | ||||
| Create a reaction | — |
|
||
| List reactions | — |
|
||
| Delete a reaction | — |
|
||
| Media & attachments | ||||
| Upload media as a file attachment | — |
|
||
| Download media |
With User authentication:
|
|||
| Get a message attachment | — |
|
||
To synchronously receive and respond to user interactions
The following table lists common ways that users interact with Chat apps and whether authentication is required or supported:
| Scenario | No authentication required | User authentication supported | App authentication supported | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Receive messages from: |
|
|||||||||||||||
| Respond to messages: |
|
|||||||||||||||
| Send new messages: |
|
|||||||||||||||
Related topics
- For an overview of authentication and authorization in Google Workspace, see Learn about authentication & authorization.
- For an overview of authentication and authorization in Google Cloud, see Authentication overview.
- To learn more about service accounts, see Service accounts.
- To learn more about how Google APIs leverage OAuth 2.0, see Using OAuth 2.0 to Access Google APIs.
- Set up authentication and authorization with user credentials or a service account.