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

# Quickstart

> Let's get you up and running with the Commerce Engine Storefront API. This guide covers the basics: obtaining credentials, understanding environments, and making your first API call.

<Info>
  **Prerequisites**

  Before you begin, you'll need a Commerce Engine account and at least one Store configured. You can manage your account, stores, and API credentials through the Commerce Engine Admin Portal.
</Info>

### Obtaining Credentials

You'll need two key pieces of information from the Admin Portal to interact with the Storefront API for a specific store:

1. **`store_id`**: This unique identifier represents your specific store within your Commerce Engine organization. All data (products, orders, customers, etc.) is scoped to a store. You'll find this ID in the Store settings section of the Admin Portal.
2. **API Key (`X-Api-Key`)**: This secret key is used *only* for the initial authentication step to identify your application when requesting an anonymous user token.

   <Warning>
     **Security Notice**

     Treat this key securely like a password; it should not be exposed in frontend code. Find this key in the API Credentials or Developer settings section for your store in the Admin Portal.
   </Warning>

### Environments and Base URLs

Commerce Engine provides distinct environments for development/testing and live production use:

* **Staging:** For development, testing, and integration.
  * Base URL: `https://staging.api.commercengine.io/api/v1/{store_id}/storefront`
* **Production:** For your live application serving real customers.
  * Base URL: `https://prod.api.commercengine.io/api/v1/{store_id}/storefront`

Simply replace `{store_id}` in the URL with your actual Store ID obtained from the Admin Portal. You'll switch between these base URLs as you move from development to production.

### Core Concept: Headless Interaction

Commerce Engine is a headless platform. This means we provide the backend commerce functionality via APIs, and you build the entire customer-facing frontend (the "head") – whether it's a website, mobile app, or other digital interface. You have complete control over the look, feel, and user experience.

All interactions with Commerce Engine happen through standard HTTP requests to our API endpoints. You'll typically use JSON for request and response bodies.

### Your First API Call: Step-by-Step

Every user interaction, even before they log in or sign up, should be associated with a unique identity. This is crucial for providing personalized experiences and enabling powerful server-side analytics from the very first click.

<Steps titleSize="h3">
  <Step title="Obtain an Anonymous User Token">
    The first step in any storefront integration is to obtain an **anonymous user token**. This token identifies the user's session even before they are known.

    You'll make a `POST` request to the `/auth/anonymous` endpoint, providing your store's **API Key** in the `X-Api-Key` header.

    ```bash Get Anonymous Token Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST \
      'https://staging.api.commercengine.io/api/v1/YOUR_STORE_ID/storefront/auth/anonymous' \
      --header 'X-Api-Key: YOUR_API_KEY' \
      --header 'Content-Type: application/json'
    ```

    **Response:**

    ```json Anonymous Token Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "message": "Anonymous user session initiated successfully.",
      "success": true,
      "content": {
        "user": {
          "id": "01HXXXXXXANONYMOUSUSERID",
          "is_anonymous": true,
          "is_logged_in": false,
          "first_name": null,
          "last_name": null,
          "phone": null,
          "email": null,
          "is_email_verified": false,
          "is_phone_verified": false,
          "profile_image_url": null,
          "created_at": "2023-10-27T10:00:00Z",
          "modified_at": "2023-10-27T10:00:00Z"
          // ... other user fields might be null initially
        },
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refresh_token": "def50200720ddb1c1ef789a641556a..."
      }
    }
    ```
  </Step>

  <Step title="Understand the Response">
    Key takeaways from the response:

    * `content.user.id`: A unique ID for this anonymous user.
    * `content.access_token`: A short-lived Bearer token used to authenticate subsequent API calls for this user's session.
    * `content.refresh_token`: A longer-lived token used to obtain a new `access_token` when it expires.

    <Warning>
      **Important: Token Storage**

      **Crucially, you must securely store both the `access_token` and `refresh_token` on the client-side.** We'll cover how to use and manage these tokens in the Authentication section.
    </Warning>
  </Step>

  <Step title="Make Authenticated Requests">
    Now that you have an `access_token`, you can make authenticated requests to other Storefront API endpoints by including it in the `Authorization` header:

    ```bash Example Authenticated Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X GET \
      'https://staging.api.commercengine.io/api/v1/YOUR_STORE_ID/storefront/catalog/products' \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
    ```

    You've successfully made your first authenticated call! Next, let's dive deep into authentication mechanisms.
  </Step>
</Steps>