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

# API Keys & Scopes

> Create vendor API keys and understand permission scopes

## Overview

Vendor API keys let you authenticate with the PuppetVendors API programmatically. Each key is scoped to a single vendor account and can be restricted to specific permissions.

## Key Prefixes

| Prefix    | Mode | Description                 |
| --------- | ---- | --------------------------- |
| `vk_live` | Live | Full access to real data    |
| `vk_test` | Test | For development and testing |

## Available Scopes

Every API key must have at least one scope. Each scope grants access to a specific set of endpoints.

| Scope                | Access                                                      | Endpoints                                                                                                                                            |
| -------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orders:read`        | Read orders, counts, timeline                               | `GET /orders`, `GET /orders/:id`, `GET /orders/counts`, `GET /orders/:id/timeline`                                                                   |
| `orders:write`       | Add order timeline comments                                 | `POST /orders/:id/timeline`                                                                                                                          |
| `products:read`      | Read products, counts                                       | `GET /products`, `GET /products/:id`, `GET /products/counts`                                                                                         |
| `products:write`     | Create, update, delete products, manage inventory and media | `POST /products`, `PUT /products/:id`, `DELETE /products/:id`, `PATCH /products/:id/status`, `PATCH /products/:id/inventory`, `POST /products/media` |
| `fulfillments:read`  | Read fulfillments, counts, stats, events                    | `GET /fulfillments`, `GET /fulfillments/counts`, `GET /fulfillments/stats`, `GET /fulfillments/events/:lineItemId`                                   |
| `fulfillments:write` | Create and update fulfillments, manage events               | `POST /fulfillments`, `PUT /fulfillments/:id`, `POST /fulfillments/events/:lineItemId`, `POST /fulfillments/events/bulk`                             |
| `payouts:read`       | Read payouts, transactions, pending items, summaries        | `GET /payouts`, `GET /payouts/:id`, `GET /payouts/summary`, `GET /payouts/transactions`, `GET /payouts/pending`                                      |
| `customers:read`     | Read customer list                                          | `GET /customers`                                                                                                                                     |

## Unscoped Endpoints

These endpoints work with **any valid vendor token** — no specific scope required on your API key:

| Group            | Endpoints                                                           |
| ---------------- | ------------------------------------------------------------------- |
| **Discounts**    | List, create, update, delete discounts                              |
| **Profile**      | `GET/PUT /vendors/me/profile`, `GET/PUT /vendors/me/address`        |
| **Settings**     | Account, profile settings, shipping rates, warehouses, team members |
| **Integrations** | Shippo, ShipStation, PayPal, Stripe configuration                   |
| **Documents**    | Invoice, packing slip, shipping label generation                    |
| **Shop**         | Feature flags and product configuration                             |

## How Scopes Work

When you create an API key, you choose which scopes to include. The API rejects requests that require a scope your key doesn't have with `403 Forbidden`.

### Read vs Write

* **`:read` scopes** grant access to `GET` endpoints — listing, viewing, and exporting data
* **`:write` scopes** grant access to `POST`, `PUT`, `PATCH`, and `DELETE` endpoints — creating, updating, and deleting data

<Warning>
  Write scopes do **not** automatically include read access. If you need both, add both scopes (e.g., `products:read` and `products:write`).
</Warning>

## Managing API Keys

| Action     | Endpoint                                       | Description                                  |
| ---------- | ---------------------------------------------- | -------------------------------------------- |
| List keys  | `GET /settings/public-api/keys`                | See all your API keys (tokens are masked)    |
| Create key | `POST /settings/public-api/keys`               | Create a new key — **token shown once**      |
| Rotate key | `POST /settings/public-api/keys/:keyId/rotate` | Generate a new token, old one is invalidated |
| Delete key | `DELETE /settings/public-api/keys/:keyId`      | Permanently revoke a key                     |

<Warning>
  When you create or rotate a key, the plaintext token is returned **exactly once**. Store it securely — you cannot retrieve it later.
</Warning>

## Quick Start Example

```bash theme={null}
# 1. Authenticate with your vendor API key
curl -X POST https://staging-api.puppetvendors.com/authenticate \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "vk_live_abc123..."}'

# Response: {"success": true, "data": {"token": "eyJ...", "expiresIn": 86400}}

# 2. Use the JWT token for subsequent requests
curl -X GET "https://staging-api.puppetvendors.com/orders?first=10" \
  -H "x-access-token: eyJ..."
```