Authentification

Authentifier vos requêtes API avec OAuth 2.1 + PKCE, une clé API ou un cookie de session.

Trois méthodes disponibles#

Méthode	Cas d'usage	Complexité
OAuth 2.1 + PKCE	Applications tierces publiques, intégrations multi-utilisateurs	⭐⭐⭐
Clé API `sk_*`	Scripts personnels, automatisations simples	⭐
Cookie de session	Front-end interne (votre propre app Syndic+)	⭐⭐

OAuth 2.1 avec PKCE#

Flux général#

Enregistrer votre client

Endpoint Dynamic Client Registration (RFC 7591) :

POST /api/oauth/register
Content-Type: application/json

{
  "client_name": "Mon Intégration",
  "redirect_uris": ["https://mon-app.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}

Réponse : client_id (pas de client_secret avec PKCE).

Rediriger l'utilisateur vers Syndic+

Construisez l'URL d'autorisation avec code_challenge (PKCE S256) :

https://app.syndicplus.ca/api/oauth/authorize?
  client_id=abc123&
  redirect_uri=https://mon-app.com/callback&
  response_type=code&
  scope=read:co-owners write:meetings&
  code_challenge=XYZ&
  code_challenge_method=S256&
  state=random_csrf_token

Utilisateur donne son consentement

L'utilisateur voit un écran listant les portées demandées. Après approbation, il est redirigé vers redirect_uri avec ?code=...&state=....

Échanger le code contre un token

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://mon-app.com/callback&
client_id=abc123&
code_verifier=ORIGINAL_CODE_VERIFIER

Réponse :

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xyz...",
  "scope": "read:co-owners write:meetings"
}

Utiliser le token

curl https://app.syndicplus.ca/api/mcp \
  -H "Authorization: Bearer eyJhbGc..."

Rafraîchir le token#

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=xyz...&
client_id=abc123

Métadonnées du serveur#

Syndic+ publie ses métadonnées OAuth conformément à RFC 8414 :

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

Clés API (`sk_*`)#

Générer une clé#

Paramètres → Développeur → Clés API → Nouvelle clé
Donner un nom descriptif ("Script de backup", "Intégration compta")
Sélectionner les portées (read:*, write:*, admin:*)
Copier la clé — elle commence par sk_live_ ou sk_test_ et ne sera plus affichée ensuite

Utiliser#

curl https://app.syndicplus.ca/api/mcp \
  -H "Authorization: Bearer sk_live_abc123..."

Les clés API donnent un accès complet selon leurs portées. Ne les committez jamais dans un dépôt Git public. Utilisez des variables d'environnement.

Révocation#

Depuis Paramètres → Développeur, cliquer sur une clé existante pour la révoquer. La révocation est immédiate.

Pour les appels depuis votre application front-end déjà authentifiée sur Syndic+, vous pouvez simplement utiliser le cookie de session :

fetch("/api/mcp", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", ... })
});

Cette méthode n'est utile que pour les applications hébergées sur le même domaine.

Portées (scopes)#

Portée	Description
`read:co-owners`	Lire la liste des copropriétaires et unités
`write:co-owners`	Créer/modifier des copropriétaires et unités
`read:meetings`	Lire les assemblées, PV, résolutions
`write:meetings`	Créer/modifier des assemblées
`read:finances`	Lire les avis, dépenses, budgets
`write:finances`	Créer des avis de cotisation, écritures comptables
`admin:organization`	Gérer les membres de l'équipe CA
`read:compliance`	Lire le tableau de bord de conformité

Sécurité du token JWT#

Algorithme : ES256 (ECDSA sur courbe P-256)
Durée de vie de l'access token : 1 heure
Durée de vie du refresh token : 30 jours (rotation à chaque usage)
JWKS public : /.well-known/jwks.json

Erreurs d'authentification courantes#

Code	Signification
`NOT_AUTHENTICATED`	Aucun token fourni ou expiré
`INVALID_TOKEN`	Token malformé ou signature invalide
`INSUFFICIENT_SCOPE`	Le token n'a pas la portée requise
`REVOKED_TOKEN`	Clé API ou consentement révoqué
`RATE_LIMITED`	Quota dépassé — voir Limites de taux