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

# Authentication

> How to obtain and use your access token.

Authentication happens in **two steps**:

<Steps>
  <Step title="Login">
    Exchange `clientId` + `apiKey` for an **access token** (JWT) at `POST /api/v1/auth`.
  </Step>

  <Step title="Access">
    Send the token in the `Authorization: Bearer <token>` header on every request.
  </Step>
</Steps>

## Getting the token

```bash theme={null}
curl -X POST https://external-api-service.pagamerican.app/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "YOUR_CLIENT_ID", "apiKey": "YOUR_API_KEY" }'
```

| Field      | Type   | Required | Description            |
| ---------- | ------ | -------- | ---------------------- |
| `clientId` | string | ✅        | Your client identifier |
| `apiKey`   | string | ✅        | Your secret key        |

Response `200 OK`:

```json theme={null}
{ "accessToken": "eyJ..." }
```

## Using the token

```bash theme={null}
curl -G https://external-api-service.pagamerican.app/api/v1/purchases \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-urlencode "from=2026-04-01" \
  --data-urlencode "to=2026-05-01"
```

## Token lifecycle

<Warning>
  The token expires after a period. When that happens, your requests will return `401` — just call `/api/v1/auth` again to get a new one.

  **Don't generate a new token on every request** (you'll hit the rate limit). Reuse the same token until it expires.
</Warning>

## Security best practices

<CardGroup cols={2}>
  <Card title="Treat the apiKey like a password" icon="shield">
    Never expose your `apiKey` in frontend code, public repositories, or logs.
  </Card>

  <Card title="Always HTTPS" icon="lock">
    All calls must use HTTPS. Plain HTTP requests fail.
  </Card>

  <Card title="Reuse the token" icon="recycle">
    Keep the token in memory and reuse it across calls until you get a `401`.
  </Card>

  <Card title="Rotate credentials" icon="key">
    If you suspect a leak, request an `apiKey` regeneration from the PagAmerican team.
  </Card>
</CardGroup>

## Personal data (privacy)

<Note>
  The `/api/v1/purchases` response includes your customers' personal data (name, email, phone, address). Use it only for authorized purposes and store it securely.
</Note>