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

# SSO Redirection API

> Authenticate an end-user into Xoxoday's hosted StoreFront via SSO (SAML 2.0). Returns an `ssoToken` which is appended to the StoreFront redirect URL. If the user account does not exist in Xoxoday, one is created automatically.

**Redirect URL format:** ``` https://stagingstores.xoxoday.com/chef/v1/oauth/redirect/stores/{ssoToken} ```
Replace `stagingstores.xoxoday.com` with `stores.xoxoday.com` for production. The `ssoToken` is valid for **14 days**.


## Key Pointers

1. The SSO API is based on SAML 2.0 standards.
2. If the user account does not exist in Xoxoday, one will be created automatically.
3. The API returns an ssoToken which is used for redirecting the user securely into the StoreFront.

## Implementation Details

### Headers

1. `Content-Type: application/json`
2. `Authorization: Bearer <access_token>`

**Note**: [Learn how to generate access token here.](https://developers.xoxoday.com/v1.2/docs/create-your-api-key-copy-2)

### Redirection URL format

```
{OAUTH_URL}/chef/v1/oauth/redirect/stores/{ssoToken} 
```

{OAUTH_URL} for:

* Staging: [https://stagingstores.xoxoday.com](https://stagingstores.xoxoday.com)
* Production: [https://stores.xoxoday.com](https://stores.xoxoday.com)

> Note: Replace the {ssoToken} with the SSO token received in the response of this API.

### Editable Fields at Checkout

1. Email and phone values can be marked as editable or non-editable at checkout.
2. Fields can also be hidden if you don’t want them shown to the user.

### OTP Verification

You can configure OTP validation for checkout on primary email, primary phone, alternate email, or disable it.

## SSO Redirection API Request Schema

| Parameter                     | Type    | Description                                                                                                                |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `user_input`                  | String  | End user’s email address. Used to create or fetch the account in Xoxoday.                                                  |
| `tpd`                         | Object  | Third-party data object containing user identity, authorization details and any custom parameter for each user.            |
| `tpd.auth_token`              | String  | Token provided by the client. Xoxoday will use this for subsequent API calls (balance, transaction, refund, verification). |
| `tpd.unique_id`               | String  | Unique identifier for the user                                                                                             |
| `tpd.email`                   | Object  | Email configuration object for the user.                                                                                   |
| `tpd.email.default_value`     | String  | Actual email ID of the user. Can be updated without affecting account history.                                             |
| `tpd.email.editable`          | Boolean | If `false`, the user cannot edit the email at checkout.                                                                    |
| `tpd.email.hidden`            | Boolean | If `true`, the email field will be hidden at checkout.                                                                     |
| `tpd.email.support_alternate` | Boolean | If `false`, no alternate email option will be shown.                                                                       |
| `tpd.phone`                   | Object  | Phone configuration object for the user.                                                                                   |
| `tpd.phone.default_value`     | String  | Phone number of the user.                                                                                                  |
| `tpd.phone.phone_code`        | String  | Country code of the phone number (e.g., `+91`).                                                                            |
| `tpd.phone.editable`          | Boolean | If `false`, the user cannot edit the phone number at checkout.                                                             |
| `tpd.phone.hidden`            | Boolean | If `true`, the phone field will be hidden at checkout.                                                                     |
| `tpd.otp`                     | String  | Mode of OTP validation. Possible values: `primary_email`, `primary_phone`, `alternate_email`, `none`.                      |

## Response Schema

| Parameter       | Type   | Description                                                                                                                            |
| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `data.ssoToken` | String | Unique token generated upon successful validation. Used to redirect the user into Xoxoday StoreFront. Default validity is **14 days**. |


## OpenAPI

````yaml specs/storefront-api.yaml POST /sso/stores/company
openapi: 3.0.3
info:
  title: Xoxoday Storefront Integration API
  version: '1.2'
  description: >
    APIs for integrating your platform with Xoxoday's hosted StoreFront via SSO.


    **Xoxoday-hosted endpoints** (Validate Token, Refresh Token, SSO
    Redirection) are

    called **by the client against Xoxoday's servers** and resolve against the
    default server.


    ---


    **Client-implemented callback endpoints** (Get Balance, Get Profile, Refund,
    Update

    Redemption) are APIs that **Xoxoday calls on your server**. You must build
    and host

    these endpoints. The path definitions below document the exact request and
    response

    contracts Xoxoday expects. Replace `https://your-server.example.com` in the
    server

    list with your actual base URL.
servers:
  - url: https://stagingstores.xoxoday.com/chef/v1/oauth
    description: Sandbox (Xoxoday-hosted endpoints)
  - url: https://stores.xoxoday.com/chef/v1/oauth
    description: Production (Xoxoday-hosted endpoints)
  - url: https://canvas.xoxoday.com/chef/v1/oauth
    description: Testing (Xoxoday-hosted endpoints)
  - url: https://your-server.example.com
    description: Your server (client-implemented callback endpoints)
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: Token management — validate and refresh access tokens.
  - name: SSO
    description: Single Sign-On redirection into Xoxoday StoreFront.
  - name: Callbacks
    description: >
      Client-implemented APIs. Xoxoday calls these on **your server** during
      StoreFront sessions. You must build and expose these endpoints.
paths:
  /sso/stores/company:
    post:
      tags:
        - SSO
      summary: SSO Redirection API
      description: >
        Authenticate an end-user into Xoxoday's hosted StoreFront via SSO (SAML
        2.0). Returns an `ssoToken` which is appended to the StoreFront redirect
        URL. If the user account does not exist in Xoxoday, one is created
        automatically.


        **Redirect URL format:** ```
        https://stagingstores.xoxoday.com/chef/v1/oauth/redirect/stores/{ssoToken}
        ```

        Replace `stagingstores.xoxoday.com` with `stores.xoxoday.com` for
        production. The `ssoToken` is valid for **14 days**.
      operationId: ssoRedirectionStorefront
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_input
                - tpd
              properties:
                user_input:
                  type: string
                  format: email
                  description: >-
                    End user's email address. Used to create or fetch the
                    account in Xoxoday.
                  example: john.doe@example.com
                tpd:
                  type: object
                  description: >-
                    Third-party data object containing user identity and
                    authorization details.
                  required:
                    - auth_token
                    - unique_id
                  properties:
                    auth_token:
                      type: string
                      description: >
                        Token provided by you. Xoxoday will pass this back on
                        subsequent callback API calls (Get Balance, Get Profile,
                        Refund, Update Redemption).
                      example: Your own key
                    unique_id:
                      type: string
                      description: Unique identifier for the user in your system.
                      example: '736517181'
                    email:
                      type: object
                      description: Email field configuration for the StoreFront checkout.
                      properties:
                        default_value:
                          type: string
                          format: email
                          description: Actual email address of the user.
                          example: john.doe@example.com
                        editable:
                          type: boolean
                          description: >-
                            If `false`, the user cannot edit the email at
                            checkout.
                          example: true
                        hidden:
                          type: boolean
                          description: If `true`, the email field is hidden at checkout.
                          example: false
                        support_alternate:
                          type: boolean
                          description: If `false`, no alternate email option is shown.
                          example: true
                    phone:
                      type: object
                      description: Phone field configuration for the StoreFront checkout.
                      properties:
                        default_value:
                          type: string
                          description: Phone number of the user.
                          example: '987654321'
                        phone_code:
                          type: string
                          description: Country calling code (e.g. `+91`).
                          example: '+91'
                        editable:
                          type: boolean
                          description: >-
                            If `false`, the user cannot edit the phone number at
                            checkout.
                          example: false
                        hidden:
                          type: boolean
                          description: If `true`, the phone field is hidden at checkout.
                          example: false
                    otp:
                      type: string
                      enum:
                        - primary_email
                        - primary_phone
                        - alternate_email
                        - none
                      description: >
                        OTP validation mode at checkout. Use `none` to disable
                        OTP verification.
                      example: primary_email
            example:
              user_input: john.doe@example.com
              tpd:
                auth_token: Your own key
                unique_id: '736517181'
                email:
                  default_value: john.doe@example.com
                  editable: true
                  hidden: false
                  support_alternate: true
                phone:
                  default_value: '987654321'
                  phone_code: '+91'
                  editable: false
                  hidden: false
                otp: primary_email
      responses:
        '200':
          description: SSO token generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ssoToken:
                        type: string
                        description: >
                          Unique token for redirecting the user into Xoxoday
                          StoreFront. Append to the redirect URL. Valid for 14
                          days.
              example:
                data:
                  ssoToken: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
    Unauthorized:
      description: Missing or invalid access token.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <access_token>`'

````