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

# ABConvert API Authentication Guide

> How ABConvert authenticates session and public endpoints — Shopify OAuth for admin calls, no auth for storefront tracking, and the x-api-key header.

<Note>
  **Preview — this page is an early draft.** We're still verifying the API reference against the current endpoints. Fields, response shapes, and examples may change before this section is marked stable. Follow [PRO-1459](https://linear.app/abconvert/issue/PRO-1459) or ask in `#abconvert-dev` if you're integrating against this today.
</Note>

ABConvert uses different authentication models for its two endpoint categories. Understanding which model applies to an endpoint tells you exactly what headers you need to include (if any) before making a request.

## Session endpoints — Shopify OAuth

All session endpoints require a valid Shopify session. When a merchant installs ABConvert from the Shopify App Store, Shopify and the ABConvert backend exchange OAuth tokens automatically. From that point on, every request made from inside the ABConvert admin panel carries the session credentials Shopify requires.

**You do not need to manage OAuth tokens manually.** If you are building a custom integration that calls session endpoints server-side, contact ABConvert support to discuss partner access options.

### How session authentication works

1. Merchant installs ABConvert via the Shopify App Store.
2. Shopify initiates the OAuth flow and issues a permanent access token.
3. ABConvert stores the token and attaches it to all subsequent Shopify Admin API calls.
4. Your browser sessions to the ABConvert admin panel are validated against this installation.

### Example session request

Requests from the admin panel automatically include the required Shopify session headers:

```bash theme={null}
curl -X GET "https://app.abconvert.io/api/experiments" \
  -H "Authorization: Bearer <shopi...en>" \
  -H "Content-Type: application/json"
```

<Note>
  The `Authorization` header value is managed by the ABConvert app. If you are testing session endpoints directly, you must obtain a valid session token from an active app installation.
</Note>

## Public endpoints — no authentication

Public endpoints are intentionally unauthenticated. They are called from visitor browsers — by the ABConvert tracking script, the Web Pixel extension, or your own storefront JavaScript — and must be reachable without credentials.

These endpoints accept a `shop` query parameter to identify your store, but this parameter is not a security mechanism. It simply routes the request to the correct store's data.

### Example public request

```bash theme={null}
curl "https://app.abconvert.io/api/get-session"
```

```bash theme={null}
curl "https://app.abconvert.io/api/public/get-country-code"
```

```bash theme={null}
curl -X POST "https://app.abconvert.io/api/track/event?shop=your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "visitorId": "vis_xyz789",
    "eventType": "product_viewed",
    "source": "webpixel",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "experimentIds": ["exp_001"]
  }'
```

## Admin tool header — `x-api-key`

A small number of administrative endpoints (such as `GET /api/enable-script` and `POST /api/get-order`) require an internal API key passed as a request header. This key is used by ABConvert's own operational tooling and is not intended for merchant use.

```bash theme={null}
curl "https://app.abconvert.io/api/enable-script" \
  -H "x-api-key: <your-internal-api-key>"
```

<Warning>
  The `x-api-key` header is for internal administrative tooling only. Do not expose this key in client-side code or public repositories. If you believe you need access to admin tool endpoints, contact ABConvert support.
</Warning>

## Summary

| Endpoint category    | Authentication method                            | Who calls it                                       |
| -------------------- | ------------------------------------------------ | -------------------------------------------------- |
| Session endpoints    | Shopify OAuth (handled automatically by the app) | ABConvert admin panel, server-side integrations    |
| Public endpoints     | None required                                    | Storefront scripts, Web Pixel, custom integrations |
| Admin tool endpoints | `x-api-key` header                               | ABConvert internal tooling                         |