## API Keys

All YNS API requests require authentication via an API key. You can create and manage keys in the [YNS dashboard](https://yns.store/manage) under **Settings → API → API keys**.

### Key Types

| Prefix | Environment | Endpoint |
|--------|-------------|----------|
| `sk-` | Production | `yns.store` |
| `sk-s-` | Staging | `yns.cx` |

Staging keys connect to a sandbox environment where you can test without affecting real data or processing real payments.

## SDK Authentication

The Commerce SDK handles authentication automatically:

```ts
import { Commerce } from "commerce-kit";

// Reads YNS_API_KEY from environment
const commerce = Commerce();

// Or pass explicitly
const commerce = Commerce({
  token: "sk-your-api-key",
});
```

The SDK adds the API key to every request as a Bearer token in the `Authorization` header.

## Direct API Authentication

If you're calling the API directly (without the SDK), include the key in the `Authorization` header:

```bash
curl https://yns.store/api/v1/products \
  -H "Authorization: Bearer sk-your-api-key"
```

## API Key Scopes

Each API key can be scoped to a set of capabilities that control which endpoints it can access. Scopes are selected when you create a key in the dashboard.

### Available Scopes

| Scope | Description |
|-------|-------------|
| `storefront:read` | Read the public catalog, content, and checkout settings a storefront renders |
| `storefront:write` | Accept visitor submissions: contact form, newsletter signup, reviews, comments |
| `cart:write` | Create and modify carts |
| `order:lookup` | Read a single order by ID (order-confirmation page) |
| `catalog:write` | Create and edit products, variants, categories, collections, brands, inventory |
| `content:read` | Read the review queue, comment queue, and media library |
| `content:write` | Edit posts, blog categories, legal pages, media, brand kit, and socials |
| `orders:read` | List and read all orders, refunds, and shipments |
| `orders:write` | Update orders, issue refunds, create shipments |
| `customers:read` | List and read customers and their order history |
| `customers:write` | Edit customers and their addresses |
| `marketing:read` | Read coupons, promotions, newsletters, subscribers, and loyalty |
| `marketing:write` | Manage coupons, promotions, loyalty, and send newsletters |
| `messages:read` | Read the inbox and support cases |
| `messages:write` | Reply to customers and manage support cases |
| `events:read` | Read events, attendees, and check-ins |
| `events:write` | Manage events, tickets, and check-ins |
| `analytics:read` | Read sales and overview analytics |
| `settings:read` | Read store settings and connected addons |
| `settings:write` | Change store settings and addon configuration |
| `team:read` | List team members and invitations |
| `team:write` | Invite members, change roles, transfer ownership |
| `store:admin` | Reset the catalog, manage the domain, publish the store |
| `ai:write` | Generate images, spending store credits |

### Storefront Keys

When you create a key for a deployed storefront (the `YNS_API_KEY` your store template uses), select only the storefront preset: `storefront:read`, `storefront:write`, `cart:write`, and `order:lookup`. This limits what a leaked storefront key can do – it cannot read customer PII, enumerate orders, or modify store settings.

### Backward Compatibility

Keys created before scopes were introduced have no scope restrictions and continue to work on all endpoints. Only newly minted keys are constrained to their declared scopes.

### Scope Errors

If a key is missing the scope required by an endpoint, the API returns `403` with a message indicating which scope is needed:

```json
{
  "error": "This API key is missing the 'catalog:write' scope",
  "hint": "Mint a key that includes 'catalog:write', or use one with broader capabilities."
}
```

## Security Best Practices

- **Never expose API keys in client-side code.** The SDK is designed for server-side use only (Server Components, Server Actions, API routes).
- **Use staging keys for development.** Switch to production keys only in your deployed environment.
- **Rotate keys if compromised.** You can create new keys and revoke old ones from the dashboard.
- **Use environment variables.** Store keys in `.env.local` (local) or your hosting platform's environment variable settings (production).
- **Use the narrowest scopes possible.** A storefront key should only have `storefront:read`, `storefront:write`, `cart:write`, and `order:lookup`. Admin keys used by integrations should only include the scopes they actually need.