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

# Quickstart

> Create a test key and make your first Perkstar API requests.

This guide confirms authentication without changing a customer's live loyalty
record. It takes about five minutes.

<Steps>
  <Step title="Create a test key">
    In the Perkstar dashboard, open **Settings → API keys → Create API key**.
    Choose **Test**, give the key a clear name such as `Odoo development`, and
    apply the **Read only** preset.

    Store the value immediately. Perkstar never stores the plaintext key and
    cannot show it again.
  </Step>

  <Step title="Set your local variables">
    ```bash theme={null}
    export PERKSTAR_API_KEY="pk_test_replace_me"
    export PERKSTAR_API_URL="https://dashboard.perkstar.co.uk/api/v1"
    ```

    Keep API keys on your server. Do not place them in browser JavaScript,
    mobile app bundles, screenshots, source control, or support messages.
  </Step>

  <Step title="Confirm the connection">
    ```bash theme={null}
    curl "$PERKSTAR_API_URL/marketplace/ping" \
      --header "Authorization: Bearer $PERKSTAR_API_KEY"
    ```

    A successful response returns the business, currency, timezone, key mode,
    and cards available to the integration.
  </Step>

  <Step title="Read a page of customers">
    ```bash theme={null}
    curl "$PERKSTAR_API_URL/customers?limit=20" \
      --header "Authorization: Bearer $PERKSTAR_API_KEY"
    ```

    The response includes `data`, `has_more`, and `next_cursor`. Pass the cursor
    back on the next request rather than guessing page numbers.
  </Step>
</Steps>

## Make an isolated test transaction

Add **Transactions: write** to the test key. Use an existing enrolment ID from
`GET /enrollments`, then post a test transaction:

```bash theme={null}
curl --request POST "$PERKSTAR_API_URL/transactions" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: quickstart-$(date +%s)" \
  --data '{
    "enrollment_id": "replace_with_existing_enrolment_id",
    "type": "STAMP",
    "delta": 1
  }'
```

The row is marked `test_mode: true`. It does not change the customer's balance,
wallet pass, dashboard totals, or analytics.

<Warning>
  Test keys deliberately cannot create or edit live customers, enrolments, or
  webhook settings. Use existing records for end-to-end testing, then switch to
  a narrowly scoped live key after completing the go-live checklist.
</Warning>

## Next steps

* Learn the [test-mode boundaries](/fundamentals/test-mode).
* Read the [idempotency and retry rules](/fundamentals/idempotency).
* Import the [official Postman collection](/tools/postman).
* Install the [Python SDK](/sdks/python) or [TypeScript SDK](/sdks/typescript).
* Follow the [go-live checklist](/support/go-live-checklist).