---
title: "Connect Microsoft (BYO Entra app)"
method: POST
path: "/v2/mailbox-settings/microsoft"
tags: ["mailbox-settings"]
---

# Connect Microsoft (BYO Entra app)

`POST /v2/mailbox-settings/microsoft`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/mailbox-settings/microsoft`
- Auth: HTTP bearer

Registers a Nylas credential for a customer-supplied (bring-your-own) Entra
app, so the org connects via its own app instead of Stuut's shared one.
Default-app orgs do **not** need this — they go straight to the consent
flow (``/consent-url`` → ``/consent-callback``), which uses the shared
credential. After connecting, the admin completes consent as usual.

Both ``azure_tenant_id`` and ``credentials`` are required (enforced by the
request schema) — this endpoint is for BYO only.

## Request body

- MicrosoftConnectionRequest: Connect the org via a bring-your-own (BYO) Entra app. Default-app orgs don't use this — they go straight to the admin-consent flow against Stuut's shared app. This endpoint registers a Nylas credential for the customer's *own* Entra app, so all fields are required.
  - `azure_tenant_id` string, required: Customer's Entra tenant GUID.
  - `credentials` EntraCredentials, required: Customer-provided Entra app credentials.
    - `client_id` string, required
    - `client_secret` string, required

## Response `200`

Successful Response

- EmailSettings
  - `transport_provider` 'nylas' | 'sendgrid', required
  - `hybrid_mode_enabled` boolean, required
  - `microsoft` MicrosoftConnection, required: The org's Microsoft mailbox connection: consent state and Entra details.
    - `enabled` boolean, required: Whether Microsoft mailbox connections are enabled for this org.
    - `admin_consented` boolean, required: Whether Entra admin consent has been granted.
    - `admin_consented_at` string, date-time, nullable, required
    - `application_scopes` string[], required: Application (app-only) Graph scopes consented in this tenant.
    - `delegated_scopes` string[], required: Deprecated, no longer refreshed — reading tenant-wide delegated grants requires Application.Read.All. Returns whatever the last directory-backed probe recorded, and is empty for any org consented since.
    - `azure_tenant_id` string, nullable, required: Customer's Entra tenant GUID.
    - `azure_client_id` string, nullable, required: Entra app client ID — Stuut's for most tenants, the customer's for BYO.
    - `is_byo` boolean, required: True when the org supplied their own Entra app credentials.
    - `uses_legacy_entra_app` boolean, required: True when this org is on a retired shared credential — the legacy Entra app or the shared common credential — and should be prompted to re-authenticate / migrate onto its own per-tenant credential.
  - `google` GoogleConnection, required: The org's Google mailbox connection state.
    - `enabled` boolean, required: Whether Google mailbox connections are enabled for this org.
  - `centralized_inbox` CentralizedInboxSettings, required: Routing / auto-assignment config for the centralized inbox.
    - `auto_assign` boolean, required
    - `auto_assign_threshold` integer, required
    - `matching_guidelines` string, nullable, required
  - `sendgrid` SendGridSettings, required: SendGrid transport configuration.
    - `domain_name` string, nullable, required: Authenticated outbound sending domain.
    - `inbound_parse_hostname` string, nullable, required: Hostname for SendGrid Inbound Parse.
    - `effective_inbound_hostname` string, nullable, required: Resolved inbound hostname (falls back to the sending domain).
    - `has_api_key` boolean, required: True when a SendGrid API key is configured.

## Other responses

- `422`: Validation Error

---

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