Skip to main content
POST
Revoke a widget user
Call this endpoint from your backend with an API key that has the widget:write scope, for example when a visitor logs out of your app.
  • Who: name the contact with exactly one of contact_id (as returned by authenticate) or external_id (as sent to Authenticate contact by external ID). Sending neither or both is rejected; a contact that doesn’t exist in your organization returns 404.
  • Effect: every widget token the contact holds stops working on its next request, whether or not it has an expiry. The widget’s requests are then rejected with the code token_revoked.
  • Signing in again: a token you issue after the revoke works normally.
  • Stored request data: clear_http_action_overrides removes the parts you name from what authenticate stored for the contact’s AI actions: headers, query_params, path_params and body_params. Each defaults to false, so nothing is removed unless you ask. The response echoes what was cleared.
An open widget for the visitor asks its user.refreshToken for a replacement once; if your backend no longer signs them in, the chat shows that the session has ended. See Sign a visitor out.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
contact_id
string

The OpenCX contact id, as returned by authenticate-user. Send this or external_id.

Required string length: 1 - 36
external_id
string

The user's id in your system, as sent to authenticate-user-by-external-id. Send this or contact_id.

Required string length: 1 - 255
clear_http_action_overrides
object

Which stored http_action_overrides parts to remove. Every part defaults to false, so nothing is removed unless asked.

Response

Default Response

contact
object
required
revoked_at
string
required

Every widget token issued at or before this time is rejected.

cleared
object
required