Authorize with domain-wide delegation

The Mail Admin Quarantine API is designed for server-side automations such as security pipelines and SIEM or SOAR integrations. These automations authenticate with a Google Cloud service account that uses domain-wide delegation to act on behalf of a Google Workspace administrator who holds the required administrator privilege.

This page explains which OAuth 2.0 scopes the API requires and how to configure a service account and obtain an access token.

OAuth 2.0 scopes

The Admin Quarantine API uses the following OAuth 2.0 scopes:

The following table shows which scope each method accepts:

Follow the principle of least privilege: request the read-only scope for integrations that only monitor the quarantine.

If a request uses a token that doesn't include an accepted scope, the API returns a 403 error with the reason ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Create a service account

1. In the Google Cloud console, go to IAM & Admin > Service Accounts and select the Google Cloud project where you enabled the API.
2. Click Create service account, enter a name such as quarantine-api-service-account, and click Create and continue. You don't need to grant the service account any IAM roles. Click Done.
3. Open the service account and, in the Details tab, copy the OAuth 2 Client ID. It's a 21-digit number, for example 109876543210987654321. You need this ID in the next section.
4. In the Keys tab, click Add key > Create new key, select JSON, and click Create. Store the downloaded JSON key file securely.

For more information, see Create credentials for a service account.

Authorize domain-wide delegation

Authorize the service account to access the Admin Quarantine API scopes in your Google Workspace account:

1. Sign in to the Google Admin console as a super administrator.
2. Go to Security > Access and data control > API controls.
3. Under Domain-wide delegation, click Manage domain-wide delegation.
4. Click Add new.
5. In the Client ID field, enter the OAuth 2.0 Client ID of the service account. Don't enter the service account's email address.

6. In the OAuth scopes field, enter one of the following scopes:

   • For read and write access: https://www.googleapis.com/auth/gmail.admin.quarantine
   • For read-only access: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

7. Click Authorize.

For details, see Control API access with domain-wide delegation.

Obtain an access token

To call the API, the service account impersonates an administrator by setting the subject (sub) claim of the token request to the administrator's email address. The administrator must hold the required administrator privilege.

The following Python example uses the google-auth library to obtain an access token:

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

Send the token in the Authorization header of every request:

Authorization: Bearer ACCESS_TOKEN

Access tokens expire after one hour. Refresh the credentials before each batch of requests rather than caching tokens for long periods.

Troubleshoot authorization errors

Next steps

• List and search quarantined messages