Un solo percorso di codice guida interfaccia e API, così non possono mai divergere.

Uno spazio di lavoro è un confine rigido, non un filtro. Ogni operazione ricava la propria organizzazione dal contesto di autenticazione fidato — mai dal payload della richiesta — e ogni query porta un predicato sullo spazio di lavoro.

• L’id dell’organizzazione arriva dal token, mai dal corpo: un payload non può scegliere uno spazio di lavoro
• Le funzioni server ricavano il contesto dal ruolo dell’organizzazione di Better Auth; l’API lo ricava dall’hash del token, dagli scope e dalla sorgente di integrazione
• Entrambi i confini convergono sulle stesse operazioni condivise, quindi UI e API non possono divergere nel comportamento
• Le risorse legate a una sorgente verificano inoltre la sorgente di integrazione che le ha scritte

I token sono a privilegio minimo per costruzione. Scegli gli scope alla creazione, il token viene mostrato una sola volta e ne viene conservato solo l’hash SHA-256.

• Scope di lettura/scrittura/eliminazione indipendenti per ogni risorsa: prodotti, lead, contatti, aziende, trattative, ordini, clienti, giacenze, pagamenti, spedizioni, resi
• Viene salvato solo un hash SHA-256; il token in chiaro è mostrato esattamente una volta
• Lo scope minimo necessario viene verificato prima che parta qualsiasi logica di business
• Una protezione per IP sugli accessi falliti respinge un chiamante che sbaglia ripetutamente prima che la ricerca del token costi una lettura

L’acquisizione dei dati si può ritentare in sicurezza. Invia due volte lo stesso externalId e ottieni indietro lo stesso record — non un duplicato e non una sovrascrittura silenziosa.

• Ripetere un payload identico restituisce il record esistente
• Un payload diverso con lo stesso externalId restituisce un 409 IDEMPOTENCY_CONFLICT tipizzato invece di sovrascrivere i dati
• Le ripetizioni concorrenti sono serializzate da un advisory lock a livello di transazione con chiave spazio di lavoro + operazione + id esterno
• I record di idempotenza durevoli vivono nel database, quindi i nuovi tentativi restano sicuri tra deployment e istanze

I limiti a finestra fissa sono applicati nel database, così ogni istanza serverless condivide un unico contatore invece di tenerne uno proprio.

• Per spazio di lavoro + sorgente di integrazione + endpoint — un’integrazione rumorosa non può consumare il budget di un’altra
• x-ratelimit-limit e x-ratelimit-remaining nelle risposte; retry-after su un 429
• Il limite basato su Redis si aggiunge quando è configurato e ripiega con grazia sul database quando non lo è
• Il widget del browser ha un proprio limite separato e non porta mai un token Bearer dello spazio di lavoro

Ogni endpoint — sia Bearer sia webhook dei connettori — fallisce nello stesso modo strutturato, con un id di richiesta che puoi citarci.

• { error: { type, code, message, requestId } } a ogni errore
• 400 VALIDATION_ERROR · 401 UNAUTHORIZED · 402 SUBSCRIPTION_INACTIVE · 403 FORBIDDEN / PLAN_LIMIT_EXCEEDED · 404 NOT_FOUND · 409 CONFLICT · 429 RATE_LIMITED
• La validazione avviene al confine tramite Zod, quindi un payload errato non raggiunge mai la logica di business
• Gli errori interni non vengono mai divulgati: le risposte 5xx sono registrate lato server con il contesto della richiesta e senza segreti

Gli eventi in uscita sono firmati HMAC così puoi verificarci. I connettori in ingresso verificano lo schema di firma della piattaforma invece di fidarsi del mittente.

• In uscita: consegne firmate HMAC-SHA256 per eventi come deal.won, lead.converted, order.delivered
• Consegna asincrona durevole con nuovi tentativi quando QStash è configurato; consegna sincrona quando non lo è
• I connettori in ingresso verificano lo schema reale di ogni piattaforma — HMAC-SHA256, SHA1, ECDSA o OAuth — letto dalla documentazione ufficiale di quella piattaforma, mai copiato da un connettore all’altro
• Un endpoint universale accetta { resource: lead | order, data } da Zapier, Make, n8n o dal tuo backend

Un terzo confine sulle stesse operazioni condivise, così un client AI opera sullo spazio di lavoro con esattamente i permessi che avrebbe una persona.

• Streamable HTTP, senza stato — niente da installare e nessun SSE da tenere attivo
• Connessione OAuth 2.1 con un clic, oppure lo stesso token Bearer a scope limitati dell’API REST
• Gli strumenti sono proiettati dal tuo ruolo nello spazio di lavoro; ciascuno ricontrolla il proprio scope, l’abbonamento e il proprio rate limit
• Nessun accesso diretto al database: ogni strumento passa dal livello condiviso delle operazioni
• get_obriym_product_facts fornisce affermazioni sul prodotto verificate, limiti, prezzi e stato di prontezza delle integrazioni in ucraino o inglese; non valuta la configurazione di un determinato spazio di lavoro

Il contratto è messo per iscritto e tenuto allineato alle rotte che descrive.

• Specifica OpenAPI 3.1 su /api/v1/openapi.json
• Riferimento interattivo su /api-docs con un costruttore di richieste dal vivo — pubblico, senza account
• Un descrittore del widget leggibile dalle macchine su /widget.json per gli agenti che sviluppano sul confine del browser
• llms.txt, roadmap.json e changelog.json pubblicano gli stessi fatti per gli agenti AI