---
title: "Start a Google Workspace organization connection"
method: POST
path: "/v1/connect/google/org"
tags: ["Connect"]
---

# Start a Google Workspace organization connection

`POST /v1/connect/google/org`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/connect/google/org`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/zernio/apis/zernio-api/docs/v1/connect/google/org/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates an organization connection for a Google Workspace domain. A super admin then delegates Zernio's client ID with the returned scopes, and you add mailboxes without each user signing in.

### Flow

1. Add `setup.dnsRecord` (a TXT record) to the domain. It proves the domain's owner set up this connection.
2. A super admin adds `setup.clientId` with `setup.scopes` under domain-wide delegation in the Admin console.
3. Call `POST /v1/org-connections/{orgConnectionId}/verify` with any mailbox in the domain.
4. Add mailboxes with `POST /v1/org-connections/{orgConnectionId}/mailboxes`.

## Request body

- object
  - `profileId` string, required
  - `domain` string, required: The Workspace domain the admin delegates.
  - `scopes` string[], required: Areas the mailboxes get, the same as a user connect.
  - `adminEmail` string, email: A super admin, used to list the domain's users.
  - `allowedEmails` string[]: Addresses or `@domain` entries mailboxes must match. Omit for every mailbox.

## Response `201`

The connection, pending until verified

- object
  - `data` OrgConnection: A Google Workspace domain or Microsoft 365 tenant whose administrator granted Zernio access to its mailboxes once.
    - `id` string
    - `provider` 'google' | 'microsoft'
    - `status` 'pending' | 'active' | 'revoked'
    - `profileId` string
    - `areas` string[]
    - `domain` string, nullable
    - `tenantId` string, nullable
    - `adminEmail` string, nullable
    - `allowedEmails` string[], nullable
    - `lastError` string, nullable
    - `verifiedAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `setup` object: What the administrator does. Google returns `dnsRecord`, `adminConsoleUrl`, `clientId`, `scopes` and `directoryScope`; Microsoft returns `adminConsentUrl` and `applicationPermissions`.
      - `type` 'google_domain_wide_delegation' | 'microsoft_admin_consent'
      - `dnsRecord` object
        - `type` 'TXT'
        - `host` string
        - `value` string
      - `adminConsoleUrl` string, uri
      - `clientId` string, nullable
      - `scopes` string[]
      - `directoryScope` string
      - `adminConsentUrl` string, uri, nullable
      - `applicationPermissions` string[]
      - `steps` string[]

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: The key cannot write to the profile, the plan cannot take another account, or the address is not on `allowedEmails`.

## Changes

- **2026-11-10** `a79c233ebf22`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/connect/google/org/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/a79c233ebf22?raw)