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

# Nova.Pay API Authentication: Keys, Hosts & Webhooks

> Learn how to secure Nova.Pay API requests using Bearer API keys, host-restriction for public endpoints, and HTTP Basic Auth for webhook receivers.

Nova.Pay uses two authentication mechanisms depending on the endpoint you are calling. Public-facing checkout and payment endpoints are protected by **host restriction**, while administrative and management endpoints require a **Bearer API key**. Webhook receiver endpoints use a separate **HTTP Basic Auth** scheme with per-gateway credentials. Understanding which mechanism applies to each endpoint will help you integrate securely and avoid unexpected `403` errors.

## Host Restriction (Public Endpoints)

Most Nova.Pay endpoints — including checkout session creation and payment submission — do not require an API key. Instead, Nova.Pay validates the origin of every incoming request against the `allowed_hosts` list configured for your account.

<Note>
  Requests originating from `*.pay.nova.money` or `*.staging.pay.nova.money` are **always** permitted and do not need to appear in `allowed_hosts`. For all other origins, you must explicitly add the hostname in your Nova.Pay dashboard settings before going live.
</Note>

If a request arrives from a host that is not on the allowlist and is not a Nova.Pay subdomain, it is rejected with a `403 Forbidden` response regardless of whether a valid API key is present.

**When does this apply?**

* Embedding a checkout page inside your own domain
* Submitting a cart payload from your storefront front-end
* Initiating a Pix or boleto payment from a customer-facing page

## Bearer API Key

Endpoints marked **Requires API key** in the reference documentation must include your secret API key in the `Authorization` header as a `Bearer` token. You can find and rotate your API keys in the **API Keys** section of your Nova.Pay dashboard.

<ParamField header="Authorization" type="string" required>
  Your Nova.Pay secret API key, prefixed with `Bearer `. Example: `Bearer npk_live_xxxxxxxxxxxxxxxx`.
</ParamField>

<Warning>
  Never expose your secret API key in client-side JavaScript, mobile app binaries, or public repositories. Use environment variables or a secrets manager to inject the key at runtime on your server.
</Warning>

Here is an example of an authenticated request to list orders:

```http theme={null}
GET /api/v1/orders HTTP/1.1
Host: pay.nova.money
Authorization: Bearer YOUR_API_KEY
```

Your API key carries full account privileges. If you need to scope access (for example, for a third-party integration), create a separate key from the dashboard and revoke it when it is no longer needed.

## Webhook Basic Auth

Nova.Pay's webhook receiver endpoints use **HTTP Basic Auth** rather than Bearer tokens. Each payment gateway integration has its own set of credentials that you configure per gateway:

| Gateway      | Where to configure credentials                 |
| ------------ | ---------------------------------------------- |
| **Pagar.me** | Gateway settings → Pagar.me → Webhook secret   |
| **Stripe**   | Gateway settings → Stripe → Webhook secret     |
| **FocusNFe** | Gateway settings → FocusNFe → Auth credentials |

When Nova.Pay receives a webhook from one of these gateways, it validates the `Authorization: Basic <base64(username:password)>` header against the credentials you have stored. Requests with missing or incorrect credentials are rejected with `401 Unauthorized`.

<Note>
  Webhook Basic Auth credentials are distinct from your Nova.Pay API keys. Rotating your API key does not affect webhook authentication, and vice versa.
</Note>

## Error Responses

Authentication failures produce the following HTTP error codes:

* **`403 Forbidden`** — The request origin is not in your `allowed_hosts` list, or the provided API key is invalid or missing.
* **`401 Unauthorized`** — The Basic Auth credentials supplied to a webhook endpoint are incorrect.

<Tip>
  If you receive an unexpected `403` during development, confirm that your local development hostname (e.g., `localhost:3000`) has been added to `allowed_hosts` in your dashboard, or proxy requests through a Nova.Pay staging subdomain.
</Tip>

For a full list of error codes and response shapes, see the [Errors](/errors) page.


## Related topics

- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Nova.Pay API Errors: Status Codes and Response Handling](/errors.md)
- [Receive and Handle Payment Webhook Events in Nova.Pay](/guides/webhooks.md)
- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Build a Custom Nova.Pay Checkout with AI](/guides/ai-checkout-skill.md)