# Organization connection

Let a Google Workspace admin grant Zernio access to the domain's mailboxes once, then add mailboxes through the API without each user signing in.

A Google Workspace super admin approves Zernio once, through domain-wide delegation. You then add the domain's mailboxes as `google` accounts, with no sign-in from their users.

## Before you start

For one person's own mailbox, use the normal [connect](/platforms/google/connect) instead.


- A profile, and an API key with write access to it.
- Someone who can edit the domain's DNS records.
- A super admin of the Google Workspace domain.

## Create the connection

```bash
curl -X POST "https://zernio.com/api/v1/connect/google/org" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profileId": "PROFILE_ID", "domain": "acme.com", "scopes": ["email", "calendar"], "adminEmail": "admin@acme.com" }'
```

The response is the connection with `status: "pending"` and a `setup` object:

```json
{
  "data": {
    "id": "6a1f...",
    "provider": "google",
    "status": "pending",
    "domain": "acme.com",
    "setup": {
      "type": "google_domain_wide_delegation",
      "dnsRecord": { "type": "TXT", "host": "acme.com", "value": "zernio-verification=..." },
      "adminConsoleUrl": "https://admin.google.com/ac/owl/domainwidedelegation",
      "clientId": "103605271790939850349",
      "scopes": ["openid", "https://www.googleapis.com/auth/userinfo.email", "..."],
      "directoryScope": "https://www.googleapis.com/auth/admin.directory.user.readonly"
    }
  }
}
```

## Prove the domain

Add `setup.dnsRecord` to the domain's DNS as a TXT record on the root of the domain. It proves the domain's owner set up this connection for your Zernio workspace.

Every Zernio customer delegates to the same Zernio client, so Zernio needs this record to know which customer the admin meant.

## Delegate access in the Admin console

The super admin opens `setup.adminConsoleUrl` (Security, Access and data control, API controls, Manage Domain Wide Delegation) and clicks **Add new**:

- **Client ID:** paste `setup.clientId`.
- **OAuth scopes:** paste every entry of `setup.scopes`, comma separated. Add `setup.directoryScope` too to list the domain's users through Zernio.

They click **Authorize**. The new row shows Zernio's client ID and the scopes.

Google can take a few minutes to apply it.

## Verify the connection

```bash
curl -X POST "https://zernio.com/api/v1/org-connections/ORG_CONNECTION_ID/verify" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "anyone@acme.com" }'
```

Zernio checks the TXT record and requests a token for that mailbox with every scope. On success the connection is `active`. Otherwise it answers `409` `org_grant_incomplete` with what is missing.

## Add mailboxes

List the domain's users (needs `adminEmail` and the directory scope):

```bash
curl "https://zernio.com/api/v1/org-connections/ORG_CONNECTION_ID/users" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

Add one:

```bash
curl -X POST "https://zernio.com/api/v1/org-connections/ORG_CONNECTION_ID/mailboxes" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@acme.com" }'
```

The answer is a `google` account (`201`, or `200` when the address was already on the profile). Use its `_id` with every email, calendar, files and contacts endpoint.

`account.connected` fires and push notifications start, exactly like a connected account.

## Limit which mailboxes you can add

Set `allowedEmails` on create, or later with `PATCH /v1/org-connections/{id}`. Entries are addresses (`ana@acme.com`) or domains (`@sales.acme.com`).

Mailboxes outside the list cannot be added. Ones already added answer `401` `reconnect_required` until the list includes them again.

## How it behaves

- Each mailbox counts as one connected account, like any other.
- Access lasts until the admin removes Zernio's client ID from domain-wide delegation, or you delete the connection.
- Gmail sending still needs a payment method on your workspace and keeps the daily limits.
- Files uses `drive.file`, the same as a user connect: Zernio sees files it created and files picked with the picker.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `409` `org_grant_incomplete`: no TXT record | The record is missing or not visible yet | Add it on the root of the domain, then wait a few minutes. |
| `409` `org_grant_incomplete`: `unauthorized_client` | The client ID or a scope is not delegated | Check the Admin console row lists every scope. |
| `409` on add with `invalid_grant` | The address is not an active user of the domain | Use an existing, unsuspended user. |
| `401` `reconnect_required` on a mailbox | The connection was deleted, the delegation removed, or the address left `allowedEmails` | Fix the grant, then call the endpoint again. |

## Related

- [Microsoft organization connection](/platforms/microsoft/organization)
- [Connect](/platforms/google/connect)
- [Limits & errors](/platforms/google/reference)