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

# Authenticate with the Appstle Loyalty API

> Create an API key in the Appstle dashboard, pass it in the X-API-Key header on every request, and manage up to 10 keys per store with per-key revocation.

Every Admin API request must carry a valid API key. Keys are created in your Appstle dashboard and scoped to a single Shopify store. There is no OAuth flow — authentication is a single header on every request.

## Creating an API key

<Steps>
  <Step title="Open API Key Management">
    Log in to your Appstle admin panel and navigate to **Settings → API Key Management**.
  </Step>

  <Step title="Create a new key">
    Click **Create New Key** and enter a descriptive name that identifies the integration — for example, `Klaviyo sync`, `Mobile app`, or `Internal dashboard`. Good names make it easy to audit and revoke keys later.
  </Step>

  <Step title="Copy the key immediately">
    The full key value is shown **only once**. Copy it and store it in your secrets manager or environment variable before leaving the page. If you navigate away without copying it, you must create a new key.
  </Step>

  <Step title="Store the key securely">
    Add the key to your application as an environment variable:

    ```bash theme={null}
    APPSTLE_API_KEY=apst_your-api-key-here
    ```

    Never hard-code the key in source code or commit it to version control.
  </Step>
</Steps>

<Warning>
  API keys grant full access to your store's loyalty data. Treat them like passwords. Never expose them in client-side JavaScript, browser extensions, or public repositories.
</Warning>

## Using the API key

Include your key in the `X-API-Key` header on every Admin API request.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET \
    "https://loyalty-admin.appstle.com/api/external/customer-loyalty?shop=your-store.myshopify.com&customer_id=12345" \
    -H "X-API-Key: apst_your-api-key-here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://loyalty-admin.appstle.com/api/external/customer-loyalty?shop=your-store.myshopify.com&customer_id=12345',
    {
      headers: {
        'X-API-Key': process.env.APPSTLE_API_KEY,
      },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      'https://loyalty-admin.appstle.com/api/external/customer-loyalty',
      params={'shop': 'your-store.myshopify.com', 'customer_id': '12345'},
      headers={'X-API-Key': os.environ['APPSTLE_API_KEY']},
  )
  data = response.json()
  ```
</CodeGroup>

You can also pass the key as a query parameter, though the header approach is strongly preferred:

```
?api_key=apst_your-api-key-here
```

<Tip>
  Create one API key per integration. If a single key is compromised or a tool is decommissioned, you can revoke it without disrupting your other integrations.
</Tip>

## Key management

You can create up to **10 active API keys** per store. Each key has:

* A **display name** you choose at creation time
* A **last-used timestamp** so you can identify stale keys
* **Individual revocation** — revoking one key does not affect others

### Rotating a key safely

<Steps>
  <Step title="Create the replacement key">
    Go to **Settings → API Key Management** and create a new key with the same or updated name.
  </Step>

  <Step title="Update your integration">
    Deploy the new key value to your application and verify it works.
  </Step>

  <Step title="Revoke the old key">
    Return to the dashboard and revoke the old key. Revocation is immediate.
  </Step>
</Steps>

## Partner integration keys

If you are building an app that connects to multiple merchants' stores, use the **Partner Integration Framework** instead of asking merchants to share API keys manually.

The Partner Framework:

* Provisions a scoped `apst_` token per merchant automatically during a one-click handshake
* Lets merchants approve, review, and revoke access from their own dashboard
* Bypasses the paid API plan — merchants are never charged for partner API usage
* Revokes tokens automatically when a merchant disconnects or uninstalls Appstle

For partner-initiated connections, use your **Partner Secret** or **HMAC-SHA256** signature alongside the merchant's `X-API-Key`. See the [integration guide](/loyalty/integration-guide) for details on the `X-App-Key` legacy header and the full partner framework walkthrough.

<Note>
  New integrations should use the Partner Integration Framework. The legacy `X-App-Key` header continues to work for existing partners but is not recommended for new builds.
</Note>

## Error responses

| Status                  | Cause                                          | Resolution                                                   |
| ----------------------- | ---------------------------------------------- | ------------------------------------------------------------ |
| `401 Unauthorized`      | Key is missing, malformed, or revoked          | Check the header name and value; create a new key if revoked |
| `403 Forbidden`         | Key is valid but lacks the required permission | Verify the key's permission level in the dashboard           |
| `429 Too Many Requests` | Rate limit exceeded                            | Implement exponential backoff before retrying                |