Connections API

Maintained by: Aether365 Team Audience: Developers Scope: Connection API endpoints - managing Microsoft 365 tenant connections

Connections represent linked Microsoft 365 tenants. Each connection corresponds to a Microsoft tenant (identified by its msTenantId) that has been granted admin consent.

List Connections

Returns all Microsoft 365 tenants connected to the authenticated account.

GET /tenants/me/connections

Example Request

curl https://api.aether365.io/tenants/me/connections \
  -H "Authorization: Bearer ak_live_..."

Example Response

{
  "success": true,
  "data": [
    {
      "id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "msTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "label": "Contoso Production",
      "connectedAt": "2026-02-01T09:00:00+00:00",
      "isPrimary": true,
      "displayName": "Contoso Ltd",
      "primaryDomain": "contoso.com",
      "defaultDomain": "contoso.onmicrosoft.com",
      "country": "Ireland",
      "countryLetterCode": "IE",
      "tenantType": "AAD",
      "verifiedDomains": ["contoso.com", "contoso.onmicrosoft.com"],
      "technicalNotificationMails": ["it@contoso.com"],
      "orgCreatedAt": "2019-05-01T00:00:00+00:00",
      "orgMetadata": {},
      "orgFetchedAt": "2026-02-01T09:00:05+00:00",
      "consentLevel": "read",
      "remediationEnabled": false,
      "needsReconsent": false,
      "writeConsentedAt": null,
      "mode": "manual"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Connection identifier (UUID)
msTenantId	string	Microsoft Entra tenant ID (GUID)
label	string or null	Display label assigned during connection
connectedAt	string	ISO 8601 timestamp when the tenant was connected
isPrimary	boolean	Whether this is the currently active tenant
displayName / primaryDomain / defaultDomain	string or null	Organization metadata read from Microsoft Graph
country / countryLetterCode / tenantType	string or null	Organization metadata
verifiedDomains / technicalNotificationMails	array or null	Organization metadata
orgCreatedAt / orgFetchedAt	string or null	Organization creation time and when metadata was last fetched
orgMetadata	object or null	Additional raw organization metadata
consentLevel	string	read or write - level of admin consent granted
remediationEnabled	boolean	Whether AI Pilot remediation is enabled for this connection
needsReconsent	boolean	Whether a Graph write was rejected and consent must be re-granted
writeConsentedAt	string or null	When write consent was granted
mode	string	manual or ai_pilot

---

Activate a Connection

Sets a connected tenant as the active tenant. Dashboard views and API calls without an explicit tenant filter operate on the active tenant.

POST /tenants/me/connections/{connectionId}/activate

Path Parameters

Parameter	Type	Description
connectionId	string	The connection ID to activate

Example Request

curl -X POST https://api.aether365.io/tenants/me/connections/9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4/activate \
  -H "Authorization: Bearer ak_live_..."

Example Response

Returns the updated list of all connections (each with the base fields only):

{
  "success": true,
  "data": [
    {
      "id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "msTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "label": "Contoso Production",
      "connectedAt": "2026-02-01T09:00:00+00:00",
      "isPrimary": false
    },
    {
      "id": "9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4",
      "msTenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "label": "Contoso Staging",
      "connectedAt": "2026-03-15T14:30:00+00:00",
      "isPrimary": true
    }
  ]
}

---

Rename a Connection

Updates the display label of a connection. Send { "label": "New name" }; an empty label clears it.

PATCH /tenants/me/connections/{connectionId}

Returns the connection id, msTenantId, updated label and connectedAt. An unknown connection returns 404 NOT_FOUND.

---

Remove a Connection

Disconnects a Microsoft 365 tenant. Stops future scans for this tenant. Existing scan data is retained according to the retention policy.

DELETE /tenants/me/connections/{connectionId}

WARNING

This action cannot be undone. Reconnecting the tenant requires going through the admin consent flow again.

Path Parameters

Parameter	Type	Description
connectionId	string	The connection ID to remove

If the removed connection was the primary one, another remaining connection becomes primary automatically. Removing the last connection is allowed - it leaves the account with no primary Microsoft tenant and tears down the automatic scan schedules.

Example Request

curl -X DELETE https://api.aether365.io/tenants/me/connections/9f8e7d6c-5b4a-3c2d-1e0f-a9b8c7d6e5f4 \
  -H "Authorization: Bearer ak_live_..."

Example Response

{
  "success": true,
  "data": null
}

Errors

Code	HTTP	Description
NOT_FOUND	404	No connection with this ID exists for this tenant
VALIDATION_ERROR	400	connectionId path parameter missing