Skip to content
DutiesBook API
Open app

Revoke channel

Permanently revoke a Microsoft 365 channel. This deletes the Microsoft Graph webhook subscription, removes stored tokens, and marks the channel as revoked so it can no longer send or receive messages.

PUT /api/channels/:id/revoke

Dashboard API

This endpoint uses dashboard authentication, not external API credentials. It is intended for use from the DutiesBook dashboard or internal tooling — not from external API integrations.

id string Required
The channel's MongoDB ID

When you revoke a Microsoft 365 channel, the following steps occur in order:

  1. Token refresh (if needed) — if the stored access token is expired, DutiesBook uses the refresh token to obtain a new one before proceeding.
  2. Webhook subscription deleted — the Microsoft Graph change notification subscription is deleted so no further email events are delivered.
  3. Channel status set to revoked — the channel record is updated with status: "revoked" and a revokedAt timestamp.

Partial failure

If the webhook subscription deletion fails (e.g. the token is invalid or the subscription has already expired), the revocation continues and the channel is still marked as revoked. Webhook cleanup failure does not block the operation.

Terminal window
curl -X PUT https://app.dutiesbook.com/api/channels/:id/revoke \
-H "Authorization: Bearer <session_token>"
200 OK
{
"success": true,
"message": "Channel access revoked successfully"
}

Already revoked

If the channel is already revoked, the endpoint returns 200 OK with a success response — it is safe to call multiple times.

DisconnectedRevoked
Can receive emailsNoNo
Can send emailsNoNo
Can be reconnectedYesNo
Webhook subscriptionKeptDeleted
Conversation historyPreservedPreserved

A disconnected channel has lost its active connection (e.g. token expired) but can be reconnected via OAuth. A revoked channel is permanently deauthorized and must be re-added from scratch if needed again.

RES_001 404
CHANNEL_NOT_FOUND

The specified channel was not found or does not belong to your organization.

SRV_001 500
SERVER_ERROR

An unexpected error occurred while revoking the channel.