Authenticate requests with Novala API keys

Every request to the Novala API must be authenticated with an API key. Novala uses a dual-key model: each key pair consists of a publishable key (pk_live_…) for safe client-side or read-only use, and a secret key (sk_live_…) for server-side or write operations.

Creating an API key

Open API Keys settings

In the Novala dashboard, navigate to Settings → API Keys.

Create a key pair

Click Create Key Pair, enter a descriptive name (for example, Acumatica Integration), and click Create.

Copy your keys immediately

The secret key is shown only once. Copy both the publishable key and the secret key before closing the dialog.

The secret key cannot be retrieved after you close the creation dialog. Store it in a secrets manager immediately. If you lose it, rotate the key pair.

Passing your key

Include the key in the Authorization header of every request:

Authorization: Bearer YOUR_SECRET_KEY

curl -X GET https://app.novala.ai/api/v1/leads \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch('https://app.novala.ai/api/v1/leads', {
  headers: {
    'Authorization': `Bearer ${process.env.NOVALA_SECRET_KEY}`,
  },
});
const { data } = await response.json();

import httpx

headers = {"Authorization": f"Bearer {NOVALA_SECRET_KEY}"}
response = httpx.get("https://app.novala.ai/api/v1/leads", headers=headers)
leads = response.json()["data"]

Key types

Type	Prefix	Intended use
Publishable	`pk_live_…`	Client-side apps, read-only public operations
Secret	`sk_live_…`	Server-side integrations, write operations

Scopes

API keys carry one or more permission scopes. A request to an endpoint that requires a scope your key does not have returns 403 Forbidden. Common scopes:

Scope	Access granted
`leads.lead.read`	List and retrieve leads
`leads.lead.write`	Create leads
`pipeline`	Read and write pipeline deals
`bookings.read`	List resources and bookings, check availability
`bookings.manage`	Create and cancel bookings
`bookings.resources.manage`	Create and update bookable resources

Scopes are assigned at key creation time. If you need additional scopes, create a new key pair with the required permissions.

Error responses

A missing or invalid key returns 401 Unauthorized:

{
  "error": "Unauthorized"
}

A key that lacks the required scope returns 403 Forbidden:

{
  "error": "Forbidden"
}

Key rotation

Rotate a key pair without downtime by following this sequence:

Create a replacement key

Go to Settings → API Keys and create a new key pair with the same scopes.

Deploy the new key

Update your integration’s environment variables or secrets store to use the new key.

Revoke the old key

Once the new key is confirmed working, click the rotate icon next to the old key or delete it outright. Revoking is immediate — any request still using the old key will receive 401 Unauthorized.

You can also use the rotate action in the dashboard, which invalidates the old key after a 24-hour grace period so you have time to update your integration.

Overview

Endpoints

Authenticate requests with Novala API keys

Creating an API key

Passing your key

Key types

Scopes

Error responses

Key rotation

​Creating an API key

​Passing your key

​Key types

​Scopes

​Error responses

​Key rotation

Creating an API key

Passing your key

Key types

Scopes

Error responses

Key rotation