Référence de l'API

URL de base et format des réponses

Chaque route est servie sous le préfixe /api. En local, l'URL de base est http://localhost:8000/api. Sur un serveur, c'est l'adresse de votre API suivie de /api, la même valeur que le site et le tableau de bord lisent dans NEXT_PUBLIC_API_BASE_URL (Variables d'environnement). Les fichiers sont servis hors du préfixe : les fichiers de marque du kit sur /media/… et les fichiers téléversés sur /media/uploads/….

Les corps de requête sont en JSON, sauf les téléversements de fichiers. Chaque réponse arrive dans la même enveloppe :

{
  "success": true,
  "data": { },
  "message": ""
}

data contient le résultat. message est un court code que remplissent certaines écritures, comme project_created ou invitation_sent, et est vide sinon. Les espaces de travail, projets et tâches sont désignés par leurs identifiants publics (org_forma, prj_01) ; les membres, invitations, clés et fichiers par leur numéro. Les textes des projets et des tâches portent les deux langues sous la forme { "en": { … }, "ar": { … } }.

La vérification de santé ne demande aucun jeton :

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Tant que la base ne répond pas et ne contient pas ses tables, elle répond 503 avec "status":"unavailable" et "database":"down". La vérification de santé de l'image Docker lit ce statut, et Docker Compose ne démarre le site et le tableau de bord qu'une fois qu'elle passe.

Les navigateurs ne peuvent appeler l'API que depuis les adresses de CORS_ORIGIN. Non défini, il autorise http://localhost:3030 et http://localhost:3031, et en production l'API refuse de démarrer sans lui (problèmes de CORS).

Erreurs

Un échec garde l'enveloppe, avec success: false, data: null et le statut HTTP :

{
  "success": false,
  "data": null,
  "message": "seat_limit_reached",
  "errors": { "email": ["…"] }
}

• errors apparaît lors d'un échec de validation (400), avec les problèmes par champ.
• Un champ inconnu dans un corps est refusé avec 400 : chaque corps n'accepte que les champs listés ci-dessous.
• Quand l'API a une phrase pour l'erreur, message est cette phrase dans la langue de la requête (Accept-Language: ar pour l'arabe) : une connexion refusée, chaque 429, les inscriptions fermées, un compte protégé contre un changement de mot de passe ou d'e-mail, un secret de webhook manquant, un abonnement que Stripe n'a pas pu annuler, un rôle ou une permission de plateforme que l'appelant ne détient pas, et le mode maintenance en font partie.
• Sinon, sur 401, 403 et 404, message est une phrase générale pour le statut, et sur 400, 402, 409, 410 et 503 c'est la raison sous forme de court code (seat_limit_reached, slug_taken, over_plan_limit, payment_declined, preview_expired, invitation_expired, payment_unavailable), qu'un client transforme en sa propre phrase. Un retour à une formule inférieure refusé pour cause d'usage porte aussi blockers.
• 402 signifie un passage à une formule supérieure que le fournisseur de paiement n'a pas voulu débiter : payment_declined, payment_needs_action (la banque veut confirmer le paiement) ou payment_method_missing. La formule reste ce qu'elle était.
• Tant que le personnel de la plateforme a le mode maintenance activé, chaque route hors de la courte liste de Maintenance mode répond 503 à quiconque n'est pas du personnel de la plateforme, avec la phrase dans message et code: "maintenance_mode".
• 401 signifie pas de jeton, un jeton expiré, ou de mauvais identifiants. 403 signifie connecté sans la permission, ou une écriture dans un espace de travail suspendu. 404 répond aussi pour un espace de travail dont l'appelant n'est pas membre, si bien qu'un inconnu ne peut pas savoir quels espaces existent.
• Une requête au-delà d'une limite répond 429 (Limites par adresse).

Connexion

1. 01

   Connexion

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@northstack.example","password":"YOUR_PASSWORD"}'

   Mettez le mot de passe du seed de l'installation à la place de YOUR_PASSWORD, ou utilisez un compte à vous. data.access_token est le jeton, avec token_type Bearer, expires_in, et admin, le compte avec ses rôles de plateforme, ses permissions et ses espaces de travail.
2. 02

   Appeler une route protégée

   TerminalCopier

   curl http://localhost:8000/api/workspaces \
     -H "Authorization: Bearer YOUR_TOKEN"

   Cela liste les espaces de travail du compte avec son rôle dans chacun. Chaque route d'espace de travail prend ensuite l'identifiant public de l'espace dans son chemin :

   TerminalCopier

   curl "http://localhost:8000/api/workspaces/org_forma/projects?limit=20" \
     -H "Authorization: Bearer YOUR_TOKEN"

• remember: true signe un jeton pour 30 jours et remember: false un jeton pour 12 heures ; omis, le jeton dure JWT_EXPIRATION, 7d par défaut.
• Un e-mail inconnu et un mauvais mot de passe répondent tous deux 401 avec le même message, après le même travail de hachage du mot de passe, si bien que ni la réponse ni son délai ne disent quels e-mails ont un compte.
• Dix connexions échouées depuis une même adresse en 15 minutes répondent 429 jusqu'à ce que le plus ancien échec ait 15 minutes (RATE_LIMIT_LOGIN). Les connexions réussies ne sont pas comptées.
• Les jetons sont sans état : POST /api/auth/logout répond aussitôt, et se déconnecter revient à ce que le client oublie son jeton.

Espaces de travail et permissions

• Les routes d'espace de travail commencent par /api/workspaces/:workspaceId, l'identifiant public de l'espace. À chaque requête, l'API vérifie que l'appelant y a une appartenance active (sinon 404) et détient la permission que nomme la route (sinon 403). Le rôle est celui de l'appartenance : une même personne peut être propriétaire d'un espace et admin d'un autre.
• Un espace de travail contient quatre rôles (owner, admin, member, billing) et sa propre matrice de 14 permissions : workspace.read, workspace.update, workspace.delete, projects.read, projects.write, members.invite, members.remove, roles.manage, billing.read, billing.manage, keys.manage, audit.read, ai.read et ai.apply. Le propriétaire les détient toutes, et workspace.delete et roles.manage restent au propriétaire quoi que dise la matrice. Un changement de la matrice s'applique à la requête suivante.
• Un espace de travail suspendu garde chaque GET et refuse toute autre méthode avec 403.
• Un espace de travail en retard de paiement garde tout jusqu'à ce que BILLING_GRACE_DAYS (7 par défaut) soient écoulés ; ensuite il ne peut ni créer de projets, ni d'invitations ou de clés d'API (403), tandis que chaque lecture et chaque autre écriture continue de fonctionner.
• Les routes de plateforme (/api/platform, /api/users, /api/admins, /api/roles, /api/settings) vérifient plutôt les permissions de plateforme du compte, accordées par les rôles de plateforme. Le seed crée Platform admin, avec les 21, et Support, qui lit chaque page de la plateforme et exporte les rapports. Une route qui liste plusieurs permissions en accepte n'importe laquelle.

• Équipe, rôles et permissions
• Administration de la plateforme

Listes et pagination

{ "data": [ ], "total": 12, "page": 1, "limit": 7, "totalPages": 2 }

• Les projets, les projets archivés, l'activité, les conversations du chat et leurs messages, ainsi que les organisations et les utilisateurs de la plateforme, se paginent avec page et limit, 100 par page au plus. Les valeurs par défaut sont 7 projets, 12 événements, 20 conversations et 10 organisations ou utilisateurs.
• Le personnel, les paramètres de la plateforme et les rôles de la plateforme se paginent avec page et page_count à la place (10 par défaut, 100 au plus). Les rôles de la plateforme ne se paginent que si les deux sont fournis ; sinon chaque rôle est renvoyé.
• Les listes arrivent de la plus récente à la plus ancienne (projets, utilisateurs et organisations par leur dernière modification), avec l'identifiant pour départager, sauf si un sort est donné ; les rôles de la plateforme arrivent par nom. La liste des projets renvoie aussi counts par onglet.
• Ce qui appartient à un seul espace de travail et s'affiche en entier répond sans pagination : les tâches d'un tableau, les membres, les invitations, les clés d'API, les fichiers d'un projet, les 36 dernières factures et les 8 dernières notifications.

Espaces de travail, membres et matrice de rôles

Invitations

Les e-mails d'invitation passent par les paramètres SMTP de l'API, ou dans son journal tant que SMTP_HOST est vide, lien compris.

Projets et fichiers

Créer un projet dans un espace de travail en retard de paiement dont le délai de grâce est terminé répond 403.

Tâches et tableau

Une tâche est listée et créée sous son projet, et modifiée par son propre identifiant sous l'espace de travail.

Une personne assignée qui n'est pas membre répond 400 avec assignee_not_member. Chaque changement écrit un événement dans la trace d'activité, comme task.moved avec les colonnes d'origine et d'arrivée.

Vue d'ensemble, activité, notifications et recherche

Les derniers événements de la vue d'ensemble et la cloche montrent toute la trace à un appelant avec projects.read ou audit.read, seulement les événements billing. à un appelant avec billing.read et aucun des deux, et rien à tous les autres.

Facturation, son webhook et le paiement test

• Le paiement utilise Stripe Checkout quand STRIPE_SECRET_KEY est défini, et le paiement test intégré sinon, ou chaque fois que BILLING_PROVIDER=simulator. Le paiement test ne débite personne.
• L'adresse de retour seule ne change jamais une formule : seuls le webhook signé, ou la session relue via sync, le font.
• Le prix Stripe de chaque formule est créé à la première utilisation, avec la clé de recherche northstack_<plan>_usd_<cents>_month : rien n'est donc configuré d'abord dans Stripe.
• Un paiement Stripe terminé pour un espace de travail qui a déjà un abonnement Stripe annule l'ancien, son temps inutilisé étant crédité. invoice.paid stocke une fois la facture de Stripe (les factures sont uniques par identifiant de facture du fournisseur), avec son montant et sa période, déplace la période de l'espace de travail vers celle qu'ouvre une facture, et lors d'un renouvellement applique un retour à une formule inférieure planifié pour lui.
• Sur le paiement test, l'API renouvelle chaque période à son terme (une facture payée, les 30 jours suivants, un retour à une formule inférieure planifié appliqué) et met fin à celle réglée pour être annulée. Un essai qui arrive à son terme passe en retard de paiement, avec le délai de grâce. Les compteurs d'usage repartent de zéro à chaque période. Cela s'exécute à chaque lecture de la facturation et une fois par heure.
• Pointez votre webhook Stripe vers https://<your API>/api/billing/webhooks/stripe avec les événements ci-dessus plus checkout.session.expired.

• Facturation
• Paramètres de paiement

Clés d'API et API publique

curl http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer nst_live_…"

• Le secret d'une clé de production commence par nst_live_, celui d'une clé de démo par nst_demo_. Une clé de démo ne fonctionne que tant que l'API tourne en mode démo.
• Aucune clé, une clé inconnue ou révoquée répond 401 ; une clé sans la portée de la route répond 403 ; un espace de travail suspendu refuse l'écriture.
• Chaque route sauf la liste des projets s'exécute au nom du créateur de la clé : ce qu'elle crée est enregistré comme fait par lui, avec la validation, les événements d'activité et les limites de formule du tableau de bord. Elle répond 404 une fois que le créateur a quitté l'espace de travail, et les trois écritures répondent 403 une fois que le rôle du créateur ne détient plus projects.write.
• Chaque appel compte dans les requêtes d'API de la formule, que lisent la page de facturation et les limites de la formule.

• Clés d'API

Vue d'ensemble de la plateforme et organisations

Utilisateurs, personnel, rôles et paramètres de la plateforme

La protection des mots de passe et des e-mails : un appelant autre que le compte lui-même ne peut définir son mot de passe ou changer son e-mail que s'il est Platform admin ou détient chaque permission de plateforme que détient le compte ; sinon l'API répond 403. L'e-mail est aussi protégé, car une réinitialisation du mot de passe y est envoyée.

La protection des rôles : personne ne peut accorder, retirer ou relever un rôle de plateforme au-delà de ses propres permissions, si bien que admins.assign_roles ou roles.assign_permissions seul ne mène jamais au rôle Platform admin.

Les 21 permissions de plateforme sont platform.view, reports.export, organizations.view, organizations.manage, users.view, users.create, users.update, users.delete, users.restore, admins.view, admins.create, admins.edit, admins.delete, admins.assign_roles, roles.view, roles.create, roles.edit, roles.delete, roles.assign_permissions, settings.view et settings.edit.

Paramètres publics et mode maintenance

Tant que le paramètre de plateforme maintenance_mode vaut true, chaque requête de quiconque n'est pas du personnel de la plateforme (un compte détenant platform.view) répond 503, avec code: "maintenance_mode" et le message « The platform is closed for maintenance. Please try again shortly. » Un jeton absent ou faux reçoit le même 503. Ces routes restent ouvertes à tous :

• GET /api/health et GET /api/public-settings ;
• POST /api/auth/login et POST /api/auth/logout, où la connexion refuse encore quiconque n'est pas du personnel avec le 503 une fois les identifiants corrects ;
• POST /api/billing/webhooks/stripe et le téléchargement signé des factures ;
• le point de terminaison MCP, qui garde sa propre clé, et GET /api/demo/status ;
• le POST /api/contact du site et chaque route /api/licenses, pour que le formulaire de contact et le paiement des licences continuent de fonctionner.

Tout le reste est fermé aux non-membres du personnel, y compris l'inscription, la récupération du mot de passe, les invitations, l'onboarding, l'API publique sous /api/v1, les fichiers téléversés et l'assistant. La liste est back-end/src/common/constants/maintenance.constants.ts.

Le formulaire de contact

• Un clientToken répété renvoie l'identifiant du premier message au lieu d'en stocker un second : une nouvelle tentative est donc sans risque.
• Un champ website rempli est traité comme un robot : la réponse a le même aspect, et rien n'est stocké.
• Chaque adresse peut en envoyer cinq par heure ; le suivant répond 429.
• Les messages sont stockés dans la table contact_messages et transférés à CONTACT_INBOX quand il est défini.

Le paiement des licences

• Le prix est celui du serveur lui-même, issu de back-end/src/modules/licenses/constants/license-offers.ts ; le navigateur n'en envoie jamais un.
• Une carte va vers Stripe Checkout quand STRIPE_SECRET_KEY est défini, PayPal vers PayPal quand PAYPAL_CLIENT_ID et PAYPAL_CLIENT_SECRET sont définis, et l'un comme l'autre vers le paiement test sinon. En mode démo, un fournisseur disposant de clés live n'est jamais proposé.
• Une commande est payée une seule fois, par celui qui arrive le premier entre le checkout.session.completed de Stripe sur POST /api/billing/webhooks/stripe, le confirm du retour, ou le Pay du paiement test. Celui-là seul émet la clé de licence et envoie le reçu par e-mail. checkout.session.expired marque la commande comme échouée.
• L'identifiant de la commande est une longue chaîne aléatoire que seuls portent les liens de retour de l'acheteur. Un clientToken répété répond la première commande. Chaque adresse peut démarrer dix commandes par heure.

• Le paiement des licences

Fichiers téléversés et médias

Les images et les fichiers de projet vont dans le bucket Cloudflare R2 quand ses cinq variables R2_* sont définies, et dans MEDIA_UPLOAD_DIR sinon, servis à PUBLIC_MEDIA_URL suivi de /uploads/….

Tout ce que l'API sert sous /media porte X-Content-Type-Options: nosniff, et un fichier qui n'est ni une image raster, ni un PDF, ni du texte brut, ni de l'audio ou de la vidéo (un fichier HTML ou SVG, par exemple) est envoyé avec Content-Disposition: attachment, si bien qu'il se télécharge au lieu de s'ouvrir comme une page à l'adresse de l'API. Les fichiers d'un bucket R2 sont servis par le bucket, avec le type qu'ils avaient au téléversement.

Limites par adresse

Une requête au-delà d'une limite répond 429, avec une phrase qui nomme ce qui a été limité et combien de temps attendre, comme « Too many sign-ups from this address. Wait an hour, then try again. » Les compteurs vivent dans la mémoire de l'API : un redémarrage les efface. Derrière un reverse proxy, définissez TRUST_PROXY avec le nombre de proxies devant l'API, sinon chaque visiteur est compté comme l'unique adresse du proxy.

L'assistant IA, ses conversations et ses propositions

Serveur MCP

Mises à jour de permissions en direct via socket.io

Routes du mode démo