Nouq API for apps (0.2.0)

Private app: a merchant's own integration. In the dashboard, App store → My apps & API → A private app for your store: give it a name, tick the scopes, copy the token. It works for that store only. Rotate it from the same page if it leaks.

OAuth: an app any store can install. Register the app in the developer portal with its redirect URIs and the scopes it needs. You get a client_id and a client_secret (shown once).

1. Send the merchant to https://app.nouq.net/oauth/authorize?client_id=…&redirect_uri=…&scope=products:read%20orders:read&state=…. redirect_uri must match one you registered exactly. scope is optional and defaults to all of the app's scopes. Use state to stop cross-site request forgery.

2. The merchant reviews the scopes and approves. Nouq redirects to redirect_uri?code=…&state=…&store_id=….

3. From your server, exchange the code within ten minutes:

   curl https://api.nouq.net/oauth/v1/token \
     -d grant_type=authorization_code -d code=$CODE -d redirect_uri=$REDIRECT_URI \
     -d client_id=$CLIENT_ID -d client_secret=$CLIENT_SECRET
   # {"access_token":"nouq_at_…","token_type":"bearer","scope":"products:read orders:read","store_id":"…"}
   

Tokens don't expire. They stop working when the merchant uninstalls the app, or when a new code is exchanged for the same store (each exchange revokes the previous token). Keep them server-side: they are never meant for a browser.

Installs from the Nouq app store. Once your app is listed (developer portal → your app → Store listing, then Nouq's review), merchants can install it from the app store. Those installs arrive at your redirect URI with state=nouq_marketplace, because no session of yours started them. Accept that value, then exchange the code as usual.

GET /api/v1/token tells you what your token can do. A call outside the token's scopes returns 403 with code insufficient_scope and names the scope it needs.

Set a monthly price (and an optional free trial) on your store listing. Nouq bills the merchant each month with a VAT invoice and pays you 80%. You don't handle cards or invoices. To check whether this store pays for your app, call GET /api/v1/subscription:

{ "status": "active", "price": 4900, "trial_ends_at": null, "period_end": "2026-11-20T09:00:00Z", "payment_due": false }

status is free, trialing, active or past_due. When payment_due is true the merchant has an unpaid fee. After 7 days unpaid your token returns 401 until they pay, and then it works again. Removing the app ends the subscription.

Each installation has a bucket of 40 requests that refills at 4 per second. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, you get 429 with Retry-After in seconds. Back off and retry.

Errors are RFC 7807 problem documents with a stable code. Validation errors are 422 with a fields map. The token endpoint uses OAuth's own error format ({"error":"invalid_grant"}).

Subscribe with POST /api/v1/webhooks ({"url":"https://…","topics":["order.created"]}). The answer includes the signing secret (whsec_…) once; keep it.

Each delivery is a POST with this body:

{ "id": "…event id…", "topic": "order.created", "store_id": "…", "created_at": "2026-10-20T09:00:00Z", "data": { } }

Headers: Nouq-Topic, Nouq-Event-Id, Nouq-Delivery-Id, Nouq-Store-Id and Nouq-Signature.

Verify every delivery. Nouq-Signature is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 with your secret over <t>.<raw body>. Compute it over the exact bytes you received, before parsing the JSON. Compare in constant time, and reject a t more than five minutes old.

import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 && timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

Answer any 2xx within ten seconds; do slow work after you answer. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours (8 attempts). A subscription whose deliveries run out of retries five times in a row is disabled; update it to turn it back on. Deliveries can arrive more than once or out of order: de-duplicate on the event id, and re-read the resource if order matters.

Event log and replay. GET /api/v1/webhook-deliveries lists the last 30 days with each attempt's status code, error and response. POST /api/v1/webhook-deliveries/{id}/replay sends the same payload again now. POST /api/v1/webhooks/{id}/test sends a webhook.test event. The developer portal has the same console across every store that installed your app.