Este documento contiene información específica de la API de Gmail sobre la autorización y la autenticación. Antes de leer este documento, asegúrate de leer la información general sobre la autenticación y la autorización de Google Workspace en Más información sobre la autenticación y la autorización.
Configura OAuth 2.0 para la autorización
Configura la pantalla de consentimiento de OAuth y elige permisos para definir qué información se muestra a los usuarios y revisores de apps, y registra tu app para que puedas publicarla más adelante.
Permisos de la API de Gmail
Para definir el nivel de acceso que se otorga a tu app, debes identificar y declarar los alcances de autorización. Un alcance de autorización es una cadena de URI de OAuth 2.0 que contiene el nombre de la app de Google Workspace, el tipo de datos a los que accede y el nivel de acceso. Los permisos son las solicitudes de tu app para trabajar con datos de Google Workspace, incluidos los datos de las Cuentas de Google de los usuarios.
Cuando se instala tu app, se le pide al usuario que valide los alcances que usa la app. Por lo general, debes elegir el alcance más específico posible y evitar solicitar alcances que tu app no necesite. Los usuarios otorgan acceso más fácilmente a los permisos limitados y claramente descritos.
Siempre que sea posible, usa permisos no sensibles para limitar el acceso solo a las funciones específicas que necesita una app.
Permisos no sensibles
Se recomiendan los siguientes alcances de la API de Gmail para la mayoría de los casos de uso:
| Código de alcance | Descripción |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.action.compose |
Administrar borradores y enviar correos electrónicos cuando interactúes con el complemento |
https://www.googleapis.com/auth/gmail.addons.current.message.action |
Ver tus mensajes de correo electrónico cuando interactúes con el complemento |
https://www.googleapis.com/auth/gmail.labels |
Consultar y editar las etiquetas de tus correos electrónicos |
Permisos sensibles
| Código de alcance | Descripción |
|---|---|
https://www.googleapis.com/auth/gmail.addons.current.message.metadata |
Ver los metadatos de tus mensajes de correo electrónico cuando se ejecuta el complemento |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
Ver tus mensajes de correo electrónico cuando se esté ejecutando el complemento |
https://www.googleapis.com/auth/gmail.send |
Enviar correos electrónicos en tu nombre |
Permisos restringidos
| Código de alcance | Descripción |
|---|---|
https://mail.google.com/ |
Leer, redactar, enviar y borrar permanentemente todos tus correos electrónicos de Gmail
Nota: Solicita este alcance solo si tu aplicación necesita borrar de inmediato y de forma permanente los hilos y los mensajes, sin pasar por la papelera. Puedes realizar todas las demás acciones con permisos menos permisivos. |
https://www.googleapis.com/auth/gmail.readonly |
Ver tus mensajes y la configuración de correo electrónico |
https://www.googleapis.com/auth/gmail.compose |
Administrar borradores y enviar correos electrónicos |
https://www.googleapis.com/auth/gmail.insert |
Agregar correos electrónicos a tu buzón de Gmail |
https://www.googleapis.com/auth/gmail.modify |
Leer, redactar y enviar correos electrónicos desde tu Cuenta de Gmail Este alcance no permite la eliminación inmediata y permanente de hilos y mensajes, ya que omite la papelera. |
https://www.googleapis.com/auth/gmail.metadata |
Permite ver los metadatos de tus mensajes de correo electrónico, como etiquetas y encabezados, pero no el cuerpo del correo electrónico. |
https://www.googleapis.com/auth/gmail.settings.basic |
Ver, editar, crear o cambiar tus filtros y tu configuración de correo electrónico en Gmail |
https://www.googleapis.com/auth/gmail.settings.sharing |
Administra la configuración del correo confidencial, como quiénes pueden administrarlo.
Nota: Las operaciones protegidas por este alcance se restringen solo al uso administrativo. Solo están disponibles para los clientes de Google Workspace que usan una cuenta de servicio con delegación para todo el dominio. |
Los alcances de las tablas anteriores indican su sensibilidad, según las siguientes definiciones:
No sensibles: Estos permisos proporcionan el alcance de autorización más pequeño y solo requieren la Verificación de la app OAuth básica. Para obtener más información, consulta los Requisitos de verificación.
Sensibles: Estos permisos proporcionan acceso a datos específicos del usuario de Google que los usuarios autorizan para tu app. Requieren una Verificación de la app OAuth adicional. Para obtener más información, consulta Requisitos de alcance sensible y restringido.
Restringidos: Estos permisos proporcionan un amplio acceso a los datos del usuario de Google y requieren la Verificación de la App de OAuth de permisos restringidos. Para obtener más información, consulta la Política de Datos del Usuario de los Servicios de las APIs de Google y los Requisitos Adicionales para Permisos Específicos de APIs.
Si almacenas datos con alcance restringido en servidores (o los transmites), debes someterte a una evaluación de seguridad.
En la Política de datos del usuario y para desarrolladores de las APIs de Google Workspace, puedes encontrar información adicional que rige tu uso y acceso a las APIs de Gmail cuando solicitas acceder a los datos del usuario.
Si tu app requiere acceso a otras APIs de Google, también puedes agregar esos permisos. Si deseas obtener más información sobre los permisos de las APIs de Google, consulta Usa OAuth 2.0 para acceder a las APIs de Google.
Si deseas obtener más información sobre permisos específicos de OAuth 2.0, consulta Permisos de OAuth 2.0 para las APIs de Google.
Verificación de OAuth
El uso de ciertos alcances sensibles de OAuth puede requerir que tu app complete el proceso de verificación de OAuth de Google. En las Preguntas frecuentes sobre la verificación de apps de OAuth, encontrarás información para determinar si es necesario realizar la verificación y qué tipo de verificación se requiere.