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

# Authentication

Learn how we protect your information by not being accessed by attackers or how we protect you from others creating a custom storefront with your store information.

## How it works

Every SDK call requires a **storefront API key** — a `shopi_pk_` prefixed key generated from the Shopi seller dashboard. The key identifies which shop's data to serve and enforces rate limits per shop.

```typescript theme={null}
import { Shopi } from '@shopi-lk/storefront-sdk';

const shop = new Shopi({
  apiKey: 'shopi_pk_your_key_here',
});
```

## Key rules

<AccordionGroup>
  <Accordion title="Keys are per-shop, not per-developer">
    Each key is tied to one shop. A theme developer does not own or distribute keys — the **shop owner** generates their own key from the seller dashboard and provides it when configuring the theme.
  </Accordion>

  <Accordion title="Keys are public-facing but scoped">
    Storefront keys are designed to be used in browser environments. They can only read public shop data and write orders/reviews. They cannot access admin operations, other shops, or any internal Supabase resources.
  </Accordion>

  <Accordion title="Keys must start with shopi_pk_">
    The SDK validates the key format at construction time. Any key not starting with `shopi_pk_` throws immediately before any network call is made.
  </Accordion>
</AccordionGroup>

## Constructor options

```typescript theme={null}
const shop = new Shopi({
  apiKey: 'shopi_pk_...',   // required
  timeoutMs: 10000,          // optional, default 10000ms
  baseUrl: '...',            // optional, do not override in production
});
```

| Option      | Type     | Required | Default                       | Description                     |
| ----------- | -------- | -------- | ----------------------------- | ------------------------------- |
| `apiKey`    | `string` | ✅        | —                             | Must start with `shopi_pk_`     |
| `timeoutMs` | `number` | ❌        | `10000`                       | Request timeout in milliseconds |
| `baseUrl`   | `string` | ❌        | `https://apicall.shopi.lk/v1` | Do not override in production   |

## Best practices

<Warning>
  Never hardcode a real API key in a theme template, public repo, or client-side config file that gets committed to version control.
</Warning>

```typescript theme={null}
// ✅ Read from environment variable
const shop = new Shopi({
  apiKey: process.env.SHOPI_API_KEY!,
});

// ✅ Read from theme config injected by shop owner
const shop = new Shopi({
  apiKey: themeConfig.apiKey,
});

// ❌ Never do this
const shop = new Shopi({
  apiKey: 'shopi_pk_abc123realkey',
});
```

## Generating a key

Shop owners generate API keys from their Shopi seller dashboard:

**Seller Dashboard → Settings → API Keys → Generate New Key**

Keys can be scoped to specific permissions and revoked at any time without affecting other keys.