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.
Endpoint
Section titled “Endpoint”/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.
Path parameters
Section titled “Path parameters”id string Required What happens on revoke
Section titled “What happens on revoke”When you revoke a Microsoft 365 channel, the following steps occur in order:
- Token refresh (if needed) — if the stored access token is expired, DutiesBook uses the refresh token to obtain a new one before proceeding.
- Webhook subscription deleted — the Microsoft Graph change notification subscription is deleted so no further email events are delivered.
- Channel status set to
revoked— the channel record is updated withstatus: "revoked"and arevokedAttimestamp.
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.
Example request
Section titled “Example request”curl -X PUT https://app.dutiesbook.com/api/channels/:id/revoke \ -H "Authorization: Bearer <session_token>"Success response
Section titled “Success response”{ "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.
Revoked vs disconnected
Section titled “Revoked vs disconnected”| Disconnected | Revoked | |
|---|---|---|
| Can receive emails | No | No |
| Can send emails | No | No |
| Can be reconnected | Yes | No |
| Webhook subscription | Kept | Deleted |
| Conversation history | Preserved | Preserved |
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.
Errors
Section titled “Errors”RES_001 404 The specified channel was not found or does not belong to your organization.
SRV_001 500 An unexpected error occurred while revoking the channel.