Контракт під робочим простором.

Workspace — це жорстка межа, а не фільтр. Кожна операція бере організацію з довіреного контексту авторизації — ніколи з тіла запиту — і кожен запит до БД несе workspace-предикат.

• ID організації береться з токена, ніколи з body: payload не може обрати workspace
• Server functions будують контекст із ролі Better Auth organization; API — з хешу токена, scopes та integration source
• Обидві межі сходяться на тих самих спільних операціях, тож UI та API не можуть розійтися в поведінці
• Source-scoped ресурси додатково звіряють integration source, який їх записав

Токени за побудовою мають мінімальні права. Ви обираєте scopes при створенні, токен показується один раз, а в БД зберігається лише його SHA-256 хеш.

• Незалежні read/write/delete scopes на ресурс: products, leads, contacts, companies, deals, orders, customers, inventory, payments, shipments, returns
• Зберігається лише SHA-256 хеш; відкритий токен показується рівно один раз
• Найвужчий потрібний scope перевіряється до будь-якої бізнес-роботи
• Per-IP guard відхиляє того, хто постійно помиляється, ще до того, як пошук токена коштуватиме читання з БД

Приймання даних безпечно повторювати. Надішліть той самий externalId двічі — отримаєте той самий запис, а не дублікат і не тихе перезаписування.

• Повтор ідентичного payload повертає наявний запис
• Інший payload під тим самим externalId повертає типізований 409 IDEMPOTENCY_CONFLICT, а не затирає дані
• Конкурентні повтори серіалізуються advisory-локом у межах транзакції за ключем workspace + операція + external id
• Записи ідемпотентності живуть у БД, тож ретраї лишаються безпечними між деплоями та інстансами

Ліміти фіксованого вікна рахуються в базі, тож усі serverless-інстанси ділять один лічильник, а не тримають кожен свій.

• На workspace + integration source + endpoint — одна галаслива інтеграція не з'їдає бюджет іншої
• x-ratelimit-limit та x-ratelimit-remaining у відповідях; retry-after на 429
• Redis-лімітер підключається зверху, коли налаштований, і коректно деградує до БД, коли ні
• Браузерний віджет має власний окремий ліміт і ніколи не отримує Bearer-токен workspace

Кожен endpoint — і Bearer, і adapter-вебхук — падає однаково структуровано, з requestId, який можна нам процитувати.

• { error: { type, code, message, requestId } } на кожній помилці
• 400 VALIDATION_ERROR · 401 UNAUTHORIZED · 402 SUBSCRIPTION_INACTIVE · 403 FORBIDDEN / PLAN_LIMIT_EXCEEDED · 404 NOT_FOUND · 409 CONFLICT · 429 RATE_LIMITED
• Валідація на межі через Zod, тож поганий payload не доходить до бізнес-логіки
• Внутрішні помилки не витікають: 5xx фіксуються на сервері з контекстом запиту й без секретів

Вихідні події підписані HMAC, щоб ви могли перевірити нас. Вхідні адаптери перевіряють власну схему підпису платформи, а не довіряють відправнику.

• Вихідні: HMAC-SHA256 підписані доставки для подій на кшталт deal.won, lead.converted, order.delivered
• Надійна асинхронна доставка з ретраями, коли налаштований QStash; синхронна — коли ні
• Вхідні адаптери перевіряють справжню схему кожної платформи — HMAC-SHA256, SHA1, ECDSA чи OAuth — прочитану з її офіційних доків, ніколи не скопійовану з іншого адаптера
• Один універсальний endpoint приймає { resource: lead | order, data } від Zapier, Make, n8n чи вашого бекенду

Третя межа поверх тих самих спільних операцій, тож AI-клієнт керує простором рівно з тими правами, які отримала б людина.

• Streamable HTTP, stateless — нічого не треба ставити й не треба тримати SSE
• OAuth 2.1 у один клік або той самий scoped Bearer-токен, що й REST API
• Інструменти проєктуються з вашої ролі; кожен перевіряє свій scope, підписку та власний rate limit
• Жодного прямого доступу до БД: кожен інструмент іде через шар спільних операцій

Контракт записаний і тримається в синхроні з роутами, які описує.

• Специфікація OpenAPI 3.1 на /api/v1/openapi.json
• Інтерактивний довідник на /api-docs із живим конструктором запитів — публічний, без акаунта
• Машиночитний дескриптор віджета на /widget.json для агентів, що будують під браузерну межу
• llms.txt, roadmap.json і changelog.json публікують ті самі факти для AI-агентів