> For the complete documentation index, see [llms.txt](https://docs.novelsystems.ca/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.novelsystems.ca/api-authentication-and-overview.md).

# API Authentication & Overview

The Novel Systems API is how commercial trade operators drive the CPQ engine and the field service module from their own systems — an ERP that needs a priced quote back, a dispatch board that needs job status, an accounting package that needs a change order the moment it is approved.

Everything below is REST over HTTPS, JSON in and JSON out, and scoped to a single tenant.

## Base endpoint

```
https://api.novelsystems.ca/v1
```

A sandbox environment mirrors production and resets weekly:

```
https://sandbox.api.novelsystems.ca/v1
```

Production data is held in `ca-central-1`. Sandbox tenants are seeded with a sample commercial price book so you can exercise the CPQ engine before your own catalogue is loaded.

## Authentication

Every request carries a bearer token in the `Authorization` header.

```http
Authorization: Bearer <API_TOKEN>
```

Full example:

```bash
curl https://api.novelsystems.ca/v1/fsm/jobs \
  -H "Authorization: Bearer nsk_live_9f2c41ab7e0d4c8f" \
  -H "Content-Type: application/json"
```

Production keys are prefixed `nsk_live_`. Sandbox keys are prefixed `nsk_test_`. A key issued for one environment is rejected by the other.

### Key scoping

Keys are scoped per integration, not per user. Issue a separate key for each system you connect — your ERP, your accounting package, your dispatch board — because every call is attributed to its key in the tenant audit log. Sharing one key across integrations destroys that attribution, and it means rotating a compromised key takes down every integration at once rather than one.

Rotate a key from **Settings → Developer → API keys**. The previous key stays valid for 24 hours after rotation so a deployment can roll forward without a gap.

### Missing or invalid credentials

```json
{
  "type": "https://novelsystems.ca/problems/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The Authorization header was missing, malformed, or the key has been revoked."
}
```

Errors follow RFC 9457 (`application/problem+json`) throughout the API.

## Conventions

| Convention   | Detail                                                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Content type | `application/json` on request and response. Errors use `application/problem+json`.                                                         |
| Money        | Always an integer minor unit plus a currency code — `{ "amount": 128420, "currency": "CAD" }` is $1,284.20 CAD. Never a float.             |
| Margins      | Decimal fractions, not percentages. `0.28` is 28%.                                                                                         |
| Timestamps   | RFC 3339, UTC, e.g. `2026-07-30T14:02:11Z`.                                                                                                |
| Idempotency  | Send `Idempotency-Key: <uuid>` on any `POST`. A replay within 24 hours returns the original response rather than creating a second record. |
| Pagination   | Cursor-based. Responses carry `next_cursor`; pass it back as `?cursor=`.                                                                   |

## Rate limits

600 requests per minute per key, burst 60 per second. Every response carries `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Over the limit returns `429` with a `Retry-After` header — back off on that value rather than retrying immediately.

## Where to go next

* [CPQ Engine API](broken://pages/926c227ea70a396c1fd315dadd26b83b0a08aaf9) — price a commercial job and get the margin back before you commit to it.
* [FSM Field Sync API](broken://pages/b2af0c15f957e73939f9731214dff0a19db68e58) — job dispatch status and the webhooks that fire when a change order is approved.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.novelsystems.ca/api-authentication-and-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.