Tenants

Overview

A tenant in TenantCore represents a Microsoft 365 tenant that has been connected to your account via admin consent. Each tenant is owned by the user who performed the consent flow. You can only access tenants you connected. TenantCore supports up to 12 domains per connected tenant and up to 3 TenantCore mailboxes per domain, for up to 36 mailboxes per tenant. These are TenantCore product limits for the current outbound infrastructure model.

Connect a tenant

Returns the Microsoft admin consent URL for connecting a new tenant. Connecting a Microsoft 365 tenant requires a Global Administrator of that tenant to approve TenantCore’s permissions in an interactive browser session. This is a Microsoft platform requirement for any application requesting tenant-wide permissions — it cannot be automated by TenantCore or bypassed by this or any API.

GET /v1/tenants/connect-url

This endpoint does not perform the redirect itself. It returns the URL so you can send your tenant admin through it from your own onboarding flow. The redirect always returns to TenantCore’s own callback — there is one registered application, and it finishes provisioning on TenantCore’s side once the admin approves. There is no webhook for completion. After the admin approves, poll GET /v1/tenants until the tenant appears, then call POST /v1/tenants/{tenant_id}/sync to refresh discovery and Exchange readiness. Example request

curl https://api.tenantcore.io/v1/tenants/connect-url \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "consent_url": "https://login.microsoftonline.com/common/adminconsent?client_id=...&redirect_uri=...&state=...",
  "instructions": "Redirect your tenant admin to consent_url. They must be signed in as a Global Administrator of the Microsoft 365 tenant you want to connect. After they approve, poll GET /v1/tenants until the tenant appears, then call POST /v1/tenants/{tenant_id}/sync to refresh discovery and Exchange readiness."
}

Errors

Status	Code	Description
`402`	`tenant_limit_reached`	Connecting another tenant would exceed your combined tenant ceiling — checked before you send an admin through a consent flow that would fail anyway
`500`	`misconfigured`	TenantCore’s Microsoft app configuration is missing — contact support

List tenants

Returns all tenants connected to your account, ordered by connection date, most recent first.

GET /v1/tenants

Example request

curl https://api.tenantcore.io/v1/tenants \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "tenants": [
    {
      "id": "uuid",
      "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "tenant_name": "Acme Corp",
      "tenant_domain": "acmecorp.onmicrosoft.com",
      "default_domain": "acmecorp.onmicrosoft.com",
      "domain_count": 12,
      "mailbox_count": 36,
      "status": null,
      "discovery_completed": true,
      "exchange_bootstrap_status": "ready",
      "consented_at": "2025-01-15T14:32:00Z",
      "last_sync_at": "2025-04-20T08:00:00Z",
      "management_mode": "byot",
      "readiness": {
        "discovery_complete": true,
        "exchange_automation_ready": true,
        "ready_for_management": true
      }
    }
  ],
  "count": 1
}

Response fields

Field	Type	Description
`tenant_id`	string	Microsoft tenant GUID
`tenant_name`	string	Display name pulled from Microsoft
`tenant_domain`	string	The `.onmicrosoft.com` domain
`default_domain`	string	The primary verified custom domain, if set
`domain_count`	number	Total custom domains on this tenant
`mailbox_count`	number	Total mailboxes across all domains
`discovery_completed`	boolean	Whether the initial discovery sync has completed
`exchange_bootstrap_status`	string	`ready`, `pending`, or `failed` — whether Exchange automation is set up
`consented_at`	timestamp	When admin consent was given
`last_sync_at`	timestamp	Last successful discovery sync
`management_mode`	string	`byot` or `tenantcore_managed` ownership mode
`readiness`	object	Stored readiness summary derived from discovery + Exchange bootstrap state; this is not a live health check

last_sync_at reflects the last time this data was refreshed. Use POST /v1/tenants/{tenant_id}/sync when you need an immediate refresh.

Get tenant

Returns a single tenant by its Microsoft tenant GUID.

GET /v1/tenants/{tenant_id}

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Example request

curl https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "id": "uuid",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant_name": "Acme Corp",
  "tenant_domain": "acmecorp.onmicrosoft.com",
  "default_domain": "mail.acmecorp.com",
  "domain_count": 8,
  "mailbox_count": 24,
  "status": null,
  "discovery_completed": true,
  "exchange_bootstrap_status": "ready",
  "consented_at": "2025-01-15T14:32:00Z",
  "last_sync_at": "2025-04-20T08:00:00Z",
  "management_mode": "byot",
  "readiness": {
    "discovery_complete": true,
    "exchange_automation_ready": true,
    "ready_for_management": true
  }
}

The tenant detail response exposes only documented customer-facing fields. readiness summarizes stored setup state so orchestration can determine whether ordinary management actions are ready without polling a separate infrastructure-health API. Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account

Sync tenant

Runs an on-demand synchronization for one connected Microsoft 365 tenant.

POST /v1/tenants/{tenant_id}/sync

A tenant sync refreshes the Microsoft 365 state TenantCore relies on for supported management actions:

Re-checks Exchange readiness and prepares required Exchange configuration where necessary.
Ensures organization-level authenticated SMTP is enabled when the tenant is ready for that workflow.
Re-runs tenant discovery so domains, mailboxes, counts, and tenant state reflect Microsoft 365.

This is especially useful after admin consent or when changes were made directly in Microsoft 365 outside TenantCore.

This request is synchronous and can take longer than a normal API read because it communicates with Microsoft Graph and Exchange Online. Use a client timeout appropriate for Microsoft provisioning operations.

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Example request

curl -X POST \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/sync \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key"

Example response

{
  "status": "completed",
  "run_id": "sync_20260909_183500_v1",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant_name": "Acme Corp",
  "bootstrap": {
    "status": "ready"
  },
  "smtp_auth": {
    "status": "success"
  },
  "result": {
    "status": "success"
  }
}

The nested bootstrap, smtp_auth, and result objects contain the detailed results returned by TenantCore’s Microsoft 365 synchronization services. Their contents may include additional fields as Microsoft/Exchange state changes. If Exchange bootstrap is not ready yet, SMTP AUTH is not attempted and the response reports:

{
  "smtp_auth": {
    "status": "skipped",
    "message": "SMTP AUTH skipped because Exchange bootstrap is not ready",
    "skipped": true
  }
}

The discovery sync still runs so TenantCore can refresh whatever Microsoft state is currently available. Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account
`500`	`tenant_sync_failed`	TenantCore could not complete the synchronization

Delete tenant

Removes a tenant and all associated records from your TenantCore account. The Microsoft 365 tenant itself is not affected — only your local records are deleted.

DELETE /v1/tenants/{tenant_id}

This operation is irreversible. All domains, mailboxes, and sync history for this tenant will be permanently removed from TenantCore. The Microsoft tenant and its mailboxes are not modified.

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Example request

curl -X DELETE \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key"

Example response

{
  "status": "deleted",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant_name": "Acme Corp",
  "message": "Tenant and all associated records removed. The Microsoft tenant itself was not affected."
}

Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account

Keeping tenant data fresh

TenantCore periodically re-discovers domains and mailboxes for connected tenants. You can also trigger an immediate refresh at any time with:

POST /v1/tenants/{tenant_id}/sync

Use this after Microsoft admin consent, after making changes directly in Microsoft 365, or whenever you need TenantCore to reconcile its stored domains, mailboxes, counts, Exchange bootstrap state, and SMTP AUTH readiness with Microsoft. Changes made directly through TenantCore’s API are generally reflected immediately in subsequent API calls. Sync is most important for Microsoft-side changes and propagation states that occur outside the API request that initiated them.

Overview

Authentication & Errors

Infrastructure

Sending Tool Integrations

Overview

Connect a tenant

List tenants

Get tenant

Sync tenant

Delete tenant

Keeping tenant data fresh

​Overview

​Connect a tenant

​List tenants

​Get tenant

​Sync tenant

​Delete tenant

​Keeping tenant data fresh

Overview

Connect a tenant

List tenants

Get tenant

Sync tenant

Delete tenant

Keeping tenant data fresh