> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Revoke a widget user

> Sign a widget visitor out from your backend: every widget token the contact holds stops working, and stored action request data can be removed. Use on logout.

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](https://docs.open.cx/api-reference/widget/authenticate-contact-by-external-id.md)). 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](https://docs.open.cx/widget/authentication.md#sign-a-visitor-out).


## OpenAPI

````yaml post /widget/revoke-user
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /widget/revoke-user:
    post:
      summary: Revoke a widget user
      description: >-
        Signs a widget user out: every widget token the contact holds stops
        working on its next request, whether or not it has an expiry. Tokens
        issued afterwards by authenticate-user work normally. Optionally removes
        stored http_action_overrides parts. Name the contact by contact_id or
        external_id, exactly one of them.
      operationId: revokeWidgetUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeWidgetUserPayloadDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeWidgetUserResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    RevokeWidgetUserPayloadDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/RevokeWidgetUserPayloadDtoInput'
      type: object
      properties:
        contact_id:
          description: >-
            The OpenCX contact id, as returned by authenticate-user. Send this
            or external_id.
          type: string
          minLength: 1
          maxLength: 36
        external_id:
          description: >-
            The user's id in your system, as sent to
            authenticate-user-by-external-id. Send this or contact_id.
          type: string
          minLength: 1
          maxLength: 255
        clear_http_action_overrides:
          description: >-
            Which stored http_action_overrides parts to remove. Every part
            defaults to false, so nothing is removed unless asked.
          type: object
          properties:
            headers:
              description: >-
                Remove the stored http_action_overrides headers. Defaults to
                false.
              type: boolean
            query_params:
              description: >-
                Remove the stored http_action_overrides query_params. Defaults
                to false.
              type: boolean
            path_params:
              description: >-
                Remove the stored http_action_overrides path_params. Defaults to
                false.
              type: boolean
            body_params:
              description: >-
                Remove the stored http_action_overrides body_params. Defaults to
                false.
              type: boolean
    RevokeWidgetUserResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/RevokeWidgetUserResponseDto'
      type: object
      properties:
        contact:
          type: object
          properties:
            id:
              type: string
            external_id:
              type:
                - string
                - 'null'
          required:
            - id
            - external_id
          additionalProperties: false
        revoked_at:
          type: string
          description: Every widget token issued at or before this time is rejected.
        cleared:
          type: object
          properties:
            headers:
              type: boolean
            query_params:
              type: boolean
            path_params:
              type: boolean
            body_params:
              type: boolean
          required:
            - headers
            - query_params
            - path_params
            - body_params
          additionalProperties: false
      required:
        - contact
        - revoked_at
        - cleared
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.