Enregistrer une app
Chaque app commence comme un enregistrementà : un document app.App.
L’enregistrement nomme le type de client, les adresses de redirection et le
plafond d’attributions. Vous passez par l’assistant du tableau de bord, ou
par l’API REST quand vous scriptez la configuration. Dans les deux cas,
l’app devient utilisable quand son status passe à active.
Pour les agentsà : créez l’app avec
POST /Api/app/App. Le corps JSON porteslug,name,client_type,redirect_uris,allowed_originsetgrants; envoyez un cookie de session etX-Requested-With: XMLHttpRequest. La création répond201avec le document stocké et unclient_idécrit par le hook. Publiez avecPATCH /Api/app/App/{id}et{"status": "active"}. Chaque entrée d’attribution ressemble à
{"target": "crm.Contact", "actions": [{"name": "read", "required": true}]}; une cible générique répond422 wildcard_target.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Utilisez cette page quandà :
- Vous ajoutez une nouvelle app à Facet.
- Vous devez choisir entre un enregistrement public, confidentiel ou headless.
- Vous scriptez la configuration des apps et cherchez le chemin API.
Avant de commencer
Section intitulée « Avant de commencer »- Il vous faut les droits
updatesur les documentsapp.App. Les rôlesadmineteditorcréés par l’initialisation les portent. - Listez les doctypes que l’app atteindra, les adresses de retour après connexion, et les origines navigateur. Chaque attribution nomme un doctype concret.
1. Choisir le type de client
Section intitulée « 1. Choisir le type de client »-
Public — une application mono-page (SPA) qui vit dans le navigateur. Elle se connecte via l’écran de consentement avec le Proof Key for Code Exchange (PKCE) et ne détient aucun secret.
-
Confidentiel — passe par le même écran de consentement et ajoute un backend. Le backend agit via un compte de service et une clé API propre à l’app — voir Apps backend.
-
Headless — définit
no_launcher: true. Elle n’apparaît jamais dans le tableau de bordà ; on y accède via son client. Un outil en ligne de commande qui ne déploie jamais de builds définit aussino_asset: true.Les types public et confidentiel apparaissent dans le lanceur du tableau de bord tant que
no_launchern’est pas défini. Une appno_assetne peut pas porter dehost.
2. Enregistrer dans le tableau de bord
Section intitulée « 2. Enregistrer dans le tableau de bord »Ouvrez Configurer → Applications et lancez l’assistant. Choisissez une forme de départà : une app web que vous hébergez se connecte via le navigateurà ; une app backend se connecte avec une clé API. L’étape Création recueille le nom, les origines autorisées et les adresses de redirection.
L’étape Autorisations liste chaque doctype par domaine. Choisissez un niveau d’accès par doctype, et sélectionnez l’unique rôle de service pour une app backend. Les actions nommées que déclare un doctype apparaissent comme capacités supplémentaires.
La publication passe le status à active. Une app web reçoit son
client_id. Une app confidentielle émet une clé APIà; la clé brute ne
s’affiche qu’une seule fois.
3. Ou enregistrer via l’API REST
Section intitulée « 3. Ou enregistrer via l’API REST »Connectez-vous comme opérateur et gardez les cookies de session dans
cookies.txt — la séquence complète figure sous
Apps backend. Créez ensuite le document
d’appà :
curl -s -b cookies.txt -X POST https://facet.company.tld/Api/app/App \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{ "slug": "deal-board", "name": "Deal Board", "client_type": "public", "redirect_uris": ["https://deal-board.company.tld/auth/callback"], "allowed_origins": ["https://deal-board.company.tld"], "grants": [ { "target": "crm.Deal", "actions": [{ "name": "read", "required": true }, { "name": "write", "required": true }] } ] }'La création répond 201 avec le document stocké. Le hook de création a
déj à écrit client_id :
{ "data": { "slug": "deal-board", "name": "Deal Board", "client_type": "public", "status": "draft", "client_id": "01JHQ8ZV3M7Q2XK9PB4T5WY6RD", "redirect_uris": ["https://deal-board.company.tld/auth/callback"], "allowed_origins": ["https://deal-board.company.tld"], "grants": [ { "target": "crm.Deal", "actions": [{ "name": "read", "required": true }, { "name": "write", "required": true }] } ] }, "meta": { "id": "app.App.01JHQ9M4T8C3XK2PB5WY6RD7QF", "uri": "urn:facet:app:App:01JHQ9M4T8C3XK2PB5WY6RD7QF", "mid": "01JHQ9M5T8D4XK2PB5WY6RD8QG", "domain": "app", "doc_type": "App", "version": 1, "schema_version": 1, "created_at": "2026-11-13T09:00:00Z", "updated_at": "2026-11-13T09:00:00Z" }}Publiez quand l’app est prête. Une app a besoin de status: active avant
que les connexions fonctionnentà :
curl -s -b cookies.txt -X PATCH \ https://facet.company.tld/Api/app/App/01JHQ9M4T8C3XK2PB5WY6RD7QF \ -H "Content-Type: application/json" \ -H "X-Requested-With: XMLHttpRequest" \ -d '{"status": "active"}'Le script d’initialisation livre un enregistrement fourni avec Facetà :
facet-cli, la CLI de dev. C’est un exemple headless completà :
{ "slug": "facet-cli", "name": "Facet CLI", "client_type": "public", "status": "active", "no_launcher": true, "no_asset": true, "redirect_uris": [ "http://localhost:*", "http://127.0.0.1:*", "http://[::1]:*" ], "grants": [ { "target": "app.App", "actions": [ { "name": "read", "required": true }, { "name": "write", "required": true }, { "name": "delete", "required": true }, { "name": "deploy", "required": true } ] }, { "target": "app.Deployment", "actions": [{ "name": "read", "required": true }] } ]}La CLI se lie à un port local éphémèreà ; chaque entrée de redirection
épingle donc un port * sur un hôte de bouclage. Les attributions portent
deploy sur app.App parce que la CLI déploie des builds. Aucun rôle de
service n’existeà : le rôle élu vient de l’écran de consentement.
Dépannage
Section intitulée « Dépannage »La création répond 422 wildcard_target.
Une attribution nomme crm.* ou *.*. Nommez chaque doctype concret à la
place — une entrée par doctype.
Une entrée de redirection échoue à la validation avec 422.
Vérifiez la note ci-dessusà : https partout, http en bouclage seulement,
* seulement comme port sur une entrée http de bouclage, pas de fragment
ni de query.
Un PATCH qui change slug est refusé.
Le slug est immuable après la création. Le hook de mise à jour refuse tout patch qui porte la clé. Créez une nouvelle app si vous avez besoin d’un autre slug.
Fournir client_id répond 422 read_only.
Le hook de création est le seul à écrire ce champ. Ne l’envoyez pas.
Un tableau grants vide se relit sous forme {}.
Une particularité du hook de création en Lua, au passage aller-retour. Le comportement est équivalentà : les deux formes donnent une itération vide.
Voir aussi
Section intitulée « Voir aussi »- Comment fonctionnent les apps sur Facet — le modèle sur lequel repose l’enregistrement.
- CORS et origines autorisées — enregistrez les origines navigateur.
- Connexion utilisateurà : OAuth 2.1 + PKCE — la connexion que l’enregistrement rend possible.
- Maîtrer la portée des apps (attributions) — l’éditeur des attributions.
- Internes sur GitHubà : app-system.md.