Skip to main content
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.
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.
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.
​
Authorization
string
required
Your Nova.Pay secret API key, prefixed with Bearer . Example: Bearer npk_live_xxxxxxxxxxxxxxxx.
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.
Here is an example of an authenticated request to list orders:
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: 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.
Webhook Basic Auth credentials are distinct from your Nova.Pay API keys. Rotating your API key does not affect webhook authentication, and vice versa.

​
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.
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.
For a full list of error codes and response shapes, see the Errors page.

Related topics

Nova.Pay API: Payments, Checkout & Order ManagementNova.Pay API Errors: Status Codes and Response HandlingReceive and Handle Payment Webhook Events in Nova.PayWebhooks API — Handle Payment Gateway Event CallbacksBuild a Custom Nova.Pay Checkout with AI