---
title: "Handle Admin Consent Callback"
method: POST
path: "/v2/mailbox-settings/microsoft/consent-callback"
tags: ["mailbox-settings"]
---

# Handle Admin Consent Callback

`POST /v2/mailbox-settings/microsoft/consent-callback`

## 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/consent-callback`
- Auth: HTTP bearer

Unauthenticated: Microsoft redirects the browser here without a Stuut
session, so the signed ``state`` token is the only proof of who started
the flow. We verify it, derive the org from its claims, and open a tenant
session for that org. On success, stamps the consent timestamp and stores
the granted scopes; on failure, raises with the provider error.

## Request body

- ConsentCallbackRequest
  - `admin_consent` boolean, required: True if Microsoft returned admin_consent=True.
  - `tenant` string, nullable: Tenant GUID, if the provider redirect includes it. The tenant is already resolved and persisted at consent-url time, so the callback does not rely on it.
  - `state` string, required: The signed state token from the consent URL, echoed back.
  - `scope` string, nullable: Scopes consented, space-delimited.
  - `error` string, nullable: OAuth error code on failure.
  - `error_description` string, nullable

## 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/ff0ad16a55ff?raw)