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 send messages in response to a user interaction, or
asynchronously. They can also complete tasks on a user's behalf, such as
creating a Chat space or getting a list of people in a
Chat space.
Chat apps don't require authentication to respond to a
user interaction, unless the Chat app calls the
Chat API
or another Google API while
processing a response.
To send asynchronous messages or perform tasks on a user's behalf,
Chat apps make RESTful requests to the
Chat API
,
which require authentication and authorization.
Responses to user interactions don't require authentication
Google Chat apps don't need to authenticate as a user or
Chat app to receive and respond synchronously to
interaction events
.
Google Chat apps receive interaction events whenever a user interacts or
invokes a Chat app, including the following:
- A user sends a message to a Chat app.
- A user @mentions a Chat app.
- A user invokes one of the Chat app's
slash commands
.
The following diagram shows a 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 app interaction
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
Configure the OAuth consent screen and choose scopes
to define what information is displayed to users and app reviewers, and register
your app so that you can publish it later.
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.
Non-sensitive scopes
Scope code
|
Description
|
https://www.googleapis.com/auth/chat.bot
|
The
chat.bot
scope only supports service accounts. You
can't authenticate with user credentials or with
domain-wide delegation
using this scope.
Lets Chat apps view chats and send messages. Gives
access to all features available to Chat apps.
|
Sensitive scopes
Scope code
|
Description
|
https://www.googleapis.com/auth/chat.spaces
|
Create conversations and spaces and see or edit metadata (including
history settings and access settings) in Chat.
|
https://www.googleapis.com/auth/chat.spaces.create
|
Create new conversations in Chat.
|
https://www.googleapis.com/auth/chat.spaces.readonly
|
View chat and spaces in Chat.
|
https://www.googleapis.com/auth/chat.memberships
|
View, add, update, and remove members from conversations in Chat.
|
https://www.googleapis.com/auth/chat.memberships.app
|
Add and remove itself from conversations in Google Chat.
|
https://www.googleapis.com/auth/chat.memberships.readonly
|
View members in Chat conversations.
|
https://www.googleapis.com/auth/chat.messages.create
|
Compose and send messages in Chat.
|
https://www.googleapis.com/auth/chat.messages.reactions
|
View, add, and delete reactions to messages in Chat.
|
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Add reactions to a message in Chat.
|
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
View reactions to a message in Chat.
|
https://www.googleapis.com/auth/chat.users.readstate
|
View and modify last read time for Chat conversations.
|
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
View last read time for Chat conversations.
|
https://www.googleapis.com/auth/chat.admin.spaces.readonly
|
View chat and spaces owned by the administrator's domain in Chat.
|
https://www.googleapis.com/auth/chat.admin.spaces
|
View or edit chat and spaces owned by the administrator's domain in Chat.
|
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
View members and managers in conversations owned by the administrator's domain in Chat.
|
https://www.googleapis.com/auth/chat.admin.memberships
|
View, add, update and remove members and managers in conversations owned by the administrator's domain in Chat.
|
Restricted scopes
Scope code
|
Description
|
https://www.googleapis.com/auth/chat.delete
|
Delete conversations and spaces, and remove access to associated files
in Chat.
|
https://www.googleapis.com/auth/chat.import
|
Import spaces, messages, and memberships into Chat. For
more information, see
Authorize Chat apps to import data
|
https://www.googleapis.com/auth/chat.messages
|
View, compose, send, update, and delete messages, and add, view, and
delete reactions to messages.
|
https://www.googleapis.com/auth/chat.messages.readonly
|
View messages and reactions in Chat.
|
https://www.googleapis.com/auth/chat.admin.delete
|
Delete conversations and spaces owned by the administrator's domain, and remove access to associated files
in Chat.
|
The scopes in the preceding tables indicate their sensitivity, according to the
following definitions:
If your app requires access to any other Google APIs, you can add those scopes
as well. For more information about Google API scopes, see
Using OAuth 2.0 to
Access Google APIs
.
To learn more about scopes for Google Workspace APIs, see
Configure the OAuth consent screen and choose scopes
.
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.
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.
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:
For Chat app interaction events
The following table lists common ways that users interact with Chat apps and whether authentication is required or supported: