> ## 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.

> Get a verified widget contact token from a phone number alone. Use when your customers sign in with their phone and have no email address on file.

# Authenticate a widget user by phone number

Call this endpoint from your backend with an API key that has the `widget:write` scope. It returns the same verified token as [Authenticate contact](/api-reference/widget/authenticate-contact). Pass that token to the widget through `user.token`.

* **Matching:** spaces and a leading `+` in the number you send don't matter, so `+14155550123`, `14155550123`, and `+1 415 555 0123` all identify the same contact.
* **Several matches:** when more than one contact has the number, the one created first is used.
* **No match:** a new contact is created with only the phone number.
* **Validation:** the number must include its country code. A national-only number such as `0770096918` is rejected with `400`.

This endpoint only accepts a phone number. To also set a name, email, or custom data, use [Authenticate contact](/api-reference/widget/authenticate-contact).


## OpenAPI

````yaml post /widget/authenticate-user-by-phone
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/authenticate-user-by-phone:
    post:
      summary: Authenticate a widget user by phone number
      description: >-
        Returns a token for the contact with this phone number, creating the
        contact when none exists. When several contacts share the number, the
        oldest one is used.
      operationId: authenticateWidgetUserByPhone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateUserByPhonePayloadDto'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifiedWidgetContactTokenResponseDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    AuthenticateUserByPhonePayloadDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/AuthenticateUserByPhonePayloadDtoInput'
      type: object
      properties:
        phone:
          type: string
          description: Phone number including the country code, e.g. +14155550123
      required:
        - phone
    VerifiedWidgetContactTokenResponseDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/VerifiedWidgetContactTokenResponseDto'
      type: object
      properties:
        token:
          type: string
          description: The JWT token to use for further requests
        contact:
          type: object
          properties:
            id:
              type: string
          required:
            - id
          additionalProperties: false
      required:
        - token
        - contact
      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.