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

# Authentication

> API key authentication and entity-level data scoping

## API Key Authentication

All requests require an API key passed in the `X-API-Key` header:

```bash theme={null}
curl 'https://api.sbx.moduluslabs.io/reports/v1/transactions' \
  -H 'X-API-Key: sk_your_secret_key_here'
```

API keys are prefixed with `sk_` (secret key). Keep your key secure — do not expose it in client-side code, public repositories, or browser requests.

<Warning>
  Requests without a valid API key receive a `401 Unauthorized` response.
</Warning>

## Entity Scoping

Every API key is associated with an entity level in the hierarchy: **Partner**, **Merchant**, or **Branch**. Data access is automatically restricted based on your key's level.

```
Partner
├── Merchant A
│   ├── Branch 1  →  sees Branch 1 transactions only
│   └── Branch 2  →  sees Branch 2 transactions only
│   └── (Merchant A key sees all branches)
└── Merchant B
    └── Branch 3
    └── (Partner key sees everything)
```

| Key Level    | Transactions               | Merchants            | Branches          |
| ------------ | -------------------------- | -------------------- | ----------------- |
| **Partner**  | All merchants and branches | All merchants        | All branches      |
| **Merchant** | Own branches only          | Own merchant only    | Own branches only |
| **Branch**   | Own transactions only      | Parent merchant only | Own branch only   |

<Info>
  Entity scoping is applied automatically — you don't need to add any special filters. A merchant-level key will never see another merchant's data, even if you try to filter by their `merchant_id`.
</Info>

## Error Responses

### 401 Unauthorized

Returned when the API key is missing, invalid, or expired:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key."
  }
}
```

### 403 Forbidden

Returned when the API key is valid but doesn't have permission for the requested resource:

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied."
  }
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Keep keys server-side" icon="server">
    Never include API keys in frontend code, mobile apps, or public repositories. Make API calls from your backend server.
  </Accordion>

  <Accordion title="Use environment variables" icon="terminal">
    Store API keys in environment variables, not in source code:

    ```bash theme={null}
    export MODULUS_API_KEY=sk_your_secret_key_here
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly" icon="rotate">
    Contact [support@moduluslabs.io](mailto:support@moduluslabs.io) to rotate your API key if you suspect it has been compromised.
  </Accordion>

  <Accordion title="Use the minimum scope" icon="shield">
    Request a merchant-level or branch-level key if you don't need partner-wide access. Least privilege reduces the impact of key exposure.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/transaction-reporting/quickstart">
    Make your first API call
  </Card>

  <Card title="Filtering & Sorting" icon="filter" href="/docs/transaction-reporting/filtering">
    Learn all available query parameters
  </Card>
</CardGroup>