Authentication

Overview

Deckle Plus has a read-only external API for integrations — ERP syncs, MES dashboards, BI tools. It exposes orders, runs and cutting patterns, and the machine, customer and paper-type catalogues. All writes happen in the web app.

The API lives under /api/v2/** and is authenticated with a short-lived token obtained from an API key.

API Keys

Admins create keys in Settings → API. A key has a name, an optional expiry, and a set of scopes — grant only what the integration needs:

Field	Type	Description
orders:read key: orders:read	scope	List and read orders and their order widths.
runs:read key: runs:read	scope	List and read production runs and their cutting patterns.
machines:read key: machines:read	scope	List machines (name, deckle width, max blades).
customers:read key: customers:read	scope	List and read customer records.
paper-types:read key: paper-types:read	scope	List paper types with their GSM values and minimum trimming.

Treat an API key like a password

The raw key is shown once, at creation. Store it in a secrets manager, never in source control. Revoke a key from the same screen if it leaks.

Exchanging for a Token

Exchange the raw key for a JWT (valid one hour), then send that JWT on every API call.

http

POST /api/v1/auth/token
Content-Type: application/json

{ "apiKey": "<your raw API key>" }

200 OK
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tenantId": "f7a3c1b2-4d5e-6f7a-8b9c-0d1e2f3a4b5c"
}

Request Headers

Every /api/v2 request needs both the token and the tenant id from the exchange response:

http

Authorization: Bearer <token>
X-Tenant-ID: <tenantId>

A missing or wrong scope returns 403; a missing/expired token or tenant id returns 401.

Pagination & Envelope

Responses are wrapped as { "success": true, "data": … }. List endpoints paginate with 1-indexed page and a size capped at 100, and their data holds a nested data array plus a meta object with page, size, total and totalPages.

Rate Limits

Each API key has a per-hour request limit (1,000 by default). Every request through the API is logged, and an Admin can review usage against the limit on Settings → API.

Audit Trails

Orders & Customers

Was this page helpful?

Something unclear or missing? Reach out and we'll update this page.

Give Feedback