> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview.md.txt), which grants early access to certain features.

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](https://support.google.com/a/answer/162106) to act on
behalf of a Google Workspace administrator who holds the required
[administrator privilege](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#admin-privileges).

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

> [!NOTE]
> **Note:** During Developer Preview, domain-wide delegation is the supported authorization method for the Admin Quarantine API.

## OAuth 2.0 scopes

The Admin Quarantine API uses the following OAuth 2.0 scopes:

| Scope | Meaning |
|---|---|
| `https://www.googleapis.com/auth/gmail.admin.quarantine` | View and manage quarantined messages. Required to release or deny messages, individually or in batches. |
| `https://www.googleapis.com/auth/gmail.admin.quarantine.readonly` | View quarantined messages. Sufficient to list, search, and get messages, list and get quarantines, and get the status of batch operations. |

The following table shows which scope each method accepts:

| Method | `gmail.admin.quarantine` | `gmail.admin.quarantine.readonly` |
|---|---|---|
| [`customers.quarantinedMessages.list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/list.md.txt) | ✓ | ✓ |
| [`customers.quarantinedMessages.search`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/search.md.txt) | ✓ | ✓ |
| [`customers.quarantinedMessages.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/get.md.txt) | ✓ | ✓ |
| [`customers.quarantines.list`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines/list.md.txt) | ✓ | ✓ |
| [`customers.quarantines.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantines/get.md.txt) | ✓ | ✓ |
| [`customers.operations.get`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.operations/get.md.txt) | ✓ | ✓ |
| [`customers.quarantinedMessages.release`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/release.md.txt) | ✓ |   |
| [`customers.quarantinedMessages.deny`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/deny.md.txt) | ✓ |   |
| [`customers.quarantinedMessages.batchRelease`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/batchRelease.md.txt) | ✓ |   |
| [`customers.quarantinedMessages.batchDeny`](https://developers.google.com/workspace/gmail/admin-quarantine/reference/rest/v1/customers.quarantinedMessages/batchDeny.md.txt) | ✓ |   |

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**](https://console.cloud.google.com/iam-admin/serviceaccounts) and select the Google Cloud project where you [enabled the API](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#enable-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](https://developers.google.com/workspace/guides/create-credentials.md.txt#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](https://admin.google.com) 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](https://support.google.com/a/answer/162106).

## 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](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#admin-privileges).

The following Python example uses the
[`google-auth`](https://google-auth.readthedocs.io/) library to obtain an
access token:

```python
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

| HTTP status | Reason | Resolution |
|---|---|---|
| `401 UNAUTHENTICATED` | The `Authorization` header is missing, or the token is malformed or expired. | Obtain a new access token and include it as a bearer token. |
| `403 ACCESS_TOKEN_SCOPE_INSUFFICIENT` | The token doesn't include a scope that the method accepts. | Request the `https://www.googleapis.com/auth/gmail.admin.quarantine` scope for release and deny methods, and make sure the scope is authorized in the Admin console. |
| `403 PERMISSION_DENIED` | The impersonated administrator doesn't hold an admin quarantine privilege, or doesn't have access to the quarantine that holds the message. | Grant **Access Admin Quarantine** or **Access restricted quarantines** to the administrator. |
| `403 SERVICE_DISABLED` or `404 NOT_FOUND` on every method | The API isn't enabled in the Cloud project, or the project isn't enrolled in the Developer Preview Program. | [Enable the API](https://developers.google.com/workspace/gmail/admin-quarantine/guides/setup.md.txt#enable-api) and confirm your enrollment in the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview.md.txt). |

## Next steps

- [List and search quarantined messages](https://developers.google.com/workspace/gmail/admin-quarantine/guides/list-search.md.txt)