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 <token>"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "conn_abc123",
      "msTenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "label": "Contoso Production",
      "connectedAt": "2026-02-01T09:00:00Z",
      "isPrimary": true
    },
    {
      "id": "conn_def456",
      "msTenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "label": "Contoso Staging",
      "connectedAt": "2026-03-15T14:30:00Z",
      "isPrimary": false
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Connection identifier
msTenantId	string	Microsoft Entra tenant ID (GUID)
label	string	Display label assigned during connection
connectedAt	string	ISO 8601 timestamp when the tenant was connected
isPrimary	boolean	Whether this is the currently active tenant

---

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/conn_def456/activate \
  -H "Authorization: Bearer <token>"

Example Response

{
  "success": true,
  "data": {
    "id": "conn_def456",
    "msTenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "label": "Contoso Staging",
    "connectedAt": "2026-03-15T14:30:00Z",
    "isPrimary": true
  }
}

---

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

Example Request

curl -X DELETE https://api.aether365.io/tenants/me/connections/conn_def456 \
  -H "Authorization: Bearer <token>"

Example Response

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

Errors

Code	HTTP	Description
CONNECTION_NOT_FOUND	404	No connection with this ID exists for this tenant
CANNOT_REMOVE_LAST_CONNECTION	409	Cannot remove the only remaining connection