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

# Authenticate shopper

> Trigger the signup flow by sending a 6-digit one-time code to the shopper's email.

## Request

```http theme={null}
POST /auth/authenticate
Content-Type: application/json
x-shop-id: {shopId}
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+2348099887766"
}
```

## Headers

| Header         | Type   | Description                                            |
| -------------- | ------ | ------------------------------------------------------ |
| `Content-Type` | string | Always set to `application/json`.                      |
| `x-shop-id`    | string | Shop identifier to associate the user with your store. |

## Body parameters

| Field   | Type   | Required | Description                                                     |
| ------- | ------ | -------- | --------------------------------------------------------------- |
| `email` | string | Yes      | Email address that receives the verification code.              |
| `name`  | string | No       | Shopper's full name. If not provided, defaults to email prefix. |
| `phone` | string | No       | Shopper's phone number in international format.                 |

## Successful response

```json theme={null}
{
    "status": 200,
    "success": true,
    "message": "Please check your email for verification code.",
    "data": {
        "email": "jane@example.com"
    }
}
```

<Check>
  You receive `success: true`, confirming the verification code is on its way
  to the shopper's inbox.
</Check>

<Note>
  The verification code emailed to the shopper is a **6-digit number**. Submit
  it to [Verify OTP](/api-reference/endpoint/auth/verify) to complete sign-in.
</Note>

## Error response

```json theme={null}
{
    "status": 500,
    "success": false,
    "message": "Failed to process registration. Please try again.",
    "data": {}
}
```


## OpenAPI

````yaml POST /auth/authenticate
openapi: 3.1.0
info:
  title: Salesive Store API
  description: >-
    REST interface for querying products, categories, and merchandising banners
    exposed by Salesive storefronts.
  version: 1.0.0
servers:
  - description: Production
    url: https://store.salesive.com/api/v1
security:
  - BearerAuth: []
    ShopIdHeader: []
paths:
  /auth/authenticate:
    post:
      summary: Authenticate shopper
      description: >-
        Trigger the signup flow by sending a one-time code to the shopper's
        email.
      parameters:
        - $ref: '#/components/parameters/XShopIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address that receives the verification code.
                name:
                  type: string
                  description: >-
                    Shopper's full name. If not provided, defaults to email
                    prefix.
                phone:
                  type: string
                  description: Shopper's phone number in international format.
      responses:
        '200':
          description: Verification code dispatched to the shopper's email.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - success
                  - message
                  - data
                properties:
                  status:
                    type: integer
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    required:
                      - email
                    properties:
                      email:
                        type: string
                        format: email
        '400':
          description: Invalid payload.
        '500':
          description: Failed to process registration.
      security: []
components:
  parameters:
    XShopIdHeader:
      name: x-shop-id
      in: header
      description: >-
        Optional identifier that scopes responses to a specific storefront when
        the referer cannot be inferred.
      required: false
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by the Salesive Store API for authenticated shoppers.
    ShopIdHeader:
      type: apiKey
      in: header
      name: x-shop-id
      description: >-
        Optional storefront identifier sent as a header to scope responses to a
        specific shop. Try It requests remember this value once provided.

````