> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-wishlyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, store and shopper identity headers.

Every request (except `GET /openapi.json`) sends the store's API key and domain, plus the shopper's identity.

| Header | Required | Value |
| - | - | - |
| `X-Shopify-ApiKey` | Always | Your store's API key |
| `X-Shopify-Shop` | Always | The store's `myshopify.com` domain, e.g. `your-store.myshopify.com` |
| `X-Shopify-CustomerId` | Logged-in shopper | Numeric Shopify customer ID |
| `X-Shopify-SessionId` | Guest shopper | A guest ID your app creates and keeps |
| `Content-Type` | Requests with a body | `application/json` |

`GET /settings` needs only the first two headers.

## Get your API key

**1. Open API Settings**

In the Codebeans Wishlyst admin, go to **Wishlist Settings → API Settings**.

**2. Generate a key**

Click **Generate new key** and copy it. A new store has no key until you generate one.

**3. Copy the connection details**

The page also shows the shop domain and the base URL. Give all three to your developer.

> [!WARNING]
>
> **Keep the key secret.** Anyone who has it can read and change the wishlists of any shopper in your store. Use it from your own server, or from a mobile app you control. Never put it in public web code.
>
> If a key leaks, click **Generate new key**. The old key stops working at once. **Reset** restores the previous key, in case you generated a new one by mistake.

## Identifying the shopper

> [tab] Logged-in customer
>
> Send the numeric customer ID, not the `gid://` form:
>
> ```
> X-Shopify-CustomerId: 7212345678901
> ```
>
> The API checks on every call that the customer exists in the store. An unknown ID returns `401 CUSTOMER_REQUIRED`.
>
> > [!NOTE]
> >
> > The API trusts the customer ID you send, so your app must authenticate the shopper itself (for example with the Customer Account API) before calling it.

> [tab] Guest
>
> Create an ID the first time the app runs, store it on the device, and send it on every call:
>
> ```
> X-Shopify-SessionId: sid_3f1c8a2e-6b0d-4c55-9f0e-2d7a1b9c4e11
> ```
>
> If the store has guest wishlists switched off, every guest call returns `403 GUEST_DISABLED`. Ask the shopper to log in.

## Moving guest lists after login

When a guest logs in, send **both** headers once to [`POST /guest-wishlists/claim`](https://codebeans-wishlyst.mintlify.site/api-reference/endpoints/account/claim-guest). The guest's lists and shares move to the customer. The call is safe to repeat.

```bash theme={null}
curl -X POST https://codebeans-wishlist.cblyst.com/api/v1/guest-wishlists/claim \
  -H "X-Shopify-ApiKey: $WISHLYST_API_KEY" \
  -H "X-Shopify-Shop: your-store.myshopify.com" \
  -H "X-Shopify-CustomerId: 7212345678901" \
  -H "X-Shopify-SessionId: sid_3f1c8a2e-6b0d-4c55-9f0e-2d7a1b9c4e11"
```

Then stop sending the session ID and use the customer ID only.

## Authentication errors

| Status | Code | Cause |
| - | - | - |
| 401 | `UNAUTHENTICATED` | Key or shop header missing or wrong, or the app is not installed on the store |
| 401 | `CUSTOMER_REQUIRED` | No shopper identity, unknown customer ID, or a guest call without a session ID |
| 403 | `API_ACCESS_NOT_IN_PLAN` | The store's plan does not include API Access |
| 403 | `GUEST_DISABLED` | Guest call while guest wishlists are off |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.