---
title: "Start a Microsoft 365 organization connection"
method: POST
path: "/v1/connect/microsoft/org"
tags: ["Connect"]
---

# Start a Microsoft 365 organization connection

`POST /v1/connect/microsoft/org`

## Request

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

Creates an organization connection for a Microsoft 365 tenant. An administrator opens `setup.adminConsentUrl` and approves Zernio's application permissions once, then you add mailboxes without each user signing in.

After consent Microsoft sends the administrator to `redirectUrl` with `orgConnectionId`, `status` (`active`, `pending` or `denied`) and `tenant`.

Application permissions reach every mailbox in the tenant. Administrators can scope them with an Exchange Online application access policy or RBAC for Applications.

## Request body

- object
  - `profileId` string, required
  - `scopes` string[], required
  - `allowedEmails` string[]: Addresses or `@domain` entries mailboxes must match. Omit for every mailbox.
  - `redirectUrl` string, uri: Where Microsoft sends the administrator after consent.

## Response `201`

The connection, pending until an administrator consents

- 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/microsoft/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)