API — Connexion des comptes OAuth

Ces endpoints gèrent la génération des liens de connexion OAuth et la liste des comptes connectés à vos applications.

---

POST /connect-sessions

Génère un lien de connexion OAuth éphémère (15 minutes, usage unique) à envoyer à votre utilisateur. C'est l'équivalent d'une session Stripe Checkout : vous l'appelez côté serveur, vous transmettez l'URL à l'utilisateur, il clique et connecte son compte.

Requête :

POST /connect-sessions
X-Api-Secret: sk_votre_cle_api
Content-Type: application/json

Corps :

Champ	Type	Obligatoire	Description
pk	string	Oui	pushable_key de l'application
plugin	string	Non	gmail ou office365 — si fourni, l'utilisateur est redirigé directement vers le fournisseur sans passer par la page de sélection
user_id	string	Non	Identifiant de l'utilisateur dans votre système (requis en mode multiuser)
callback_url	string	Non	URL de retour après connexion réussie

{
  "pk": "pk_AbCdEfGhIjKlMnOpQrStUvWx",
  "plugin": "gmail",
  "user_id": "usr_123",
  "callback_url": "https://votre-app.com/email/callback"
}

Réponse 200 :

{
  "url": "https://connect.sendas.me/?session=gX9k2mP7nQrTvWyZaBcDeFgH...",
  "expires_at": "2026-04-11T14:35:00Z",
  "token": "gX9k2mP7nQrTvWyZaBcDeFgH..."
}

Champ	Description
url	Lien à transmettre à l'utilisateur (valable 15 min)
expires_at	Timestamp ISO 8601 d'expiration
token	Token opaque — vous pouvez le conserver pour vos logs

Comportement du lien :

• Expiration après 15 minutes
• Usage unique — invalidé dès que l'utilisateur complète le flux OAuth
• Lien expiré ou déjà utilisé → page d'erreur explicite (HTTP 410)
• L'app_id et la pushable_key ne sont jamais exposés dans l'URL

Exemple d'intégration backend :

import httpx

def generate_connect_link(user_id: str) -> str:
    resp = httpx.post(
        "https://api.sendas.me/connect-sessions",
        headers={"X-Api-Secret": API_SECRET},
        json={
            "pk":           "pk_AbCdEfGhIjKlMnOpQrStUvWx",
            "plugin":       "gmail",
            "user_id":      user_id,
            "callback_url": f"https://votre-app.com/email/callback",
        },
    )
    return resp.json()["url"]   # à afficher à l'utilisateur

Usage unique garanti

Générez un nouveau lien à chaque fois qu'un utilisateur souhaite connecter son compte. Ne réutilisez pas un lien existant — il peut déjà être expiré ou utilisé.

---

Page de connexion embarquée (lien permanent ?pk=)

Pour les cas d'intégration embarquée (iframe, widget intégré directement dans votre interface), vous pouvez utiliser un lien permanent basé sur la pushable_key. Ce lien n'expire pas et peut être réutilisé.

https://connect.sendas.me/?pk=pk_AbCdEfGhIjKlMnOpQrStUvWx

Paramètres optionnels :

Paramètre	Description
user_id	Identifiant de l'utilisateur (requis en mode multiuser)
callback_url	URL de retour après connexion

Sécurité

Le lien permanent expose la pushable_key dans l'URL. Préférez les sessions éphémères (POST /connect-sessions) pour les liens envoyés par email ou affichés dans votre interface.

---

Retour de connexion (callback_url)

Après une connexion réussie, l'utilisateur est redirigé vers votre callback_url avec les paramètres suivants :

https://votre-app.com/email/callback?status=connected&email=user@gmail.com&plugin=gmail

Paramètre	Valeur
status	connected
email	Adresse email du compte connecté
plugin	gmail ou office365

Si aucune callback_url n'est fournie, une page de confirmation est affichée sur connect.sendas.me.

---

GET /apps/{pushable_key}

Retourne les détails d'une application, incluant le nombre de comptes connectés.

Requête :

GET /apps/pk_AbCdEfGhIjKlMnOpQrStUvWx
X-Api-Secret: sk_votre_cle_api

Réponse 200 :

{
  "app_id": "moncrm",
  "name": "Mon CRM",
  "pushable_key": "pk_AbCdEfGhIjKlMnOpQrStUvWx",
  "connections_count": 3,
  "webhook_url": "https://example.com/webhook",
  "callback_url": "https://example.com/oauth/callback"
}

---

Webhook user.connected

Reçu dès qu'un utilisateur complète le flux OAuth avec succès.

{
  "event": "user.connected",
  "app_id": "moncrm",
  "data": {
    "email": "alice@gmail.com",
    "plugin": "gmail",
    "user_id": "usr_123"
  }
}

Webhook user.disconnected

Reçu quand un utilisateur se déconnecte depuis la page connect, ou quand le token est révoqué.

{
  "event": "user.disconnected",
  "app_id": "moncrm",
  "data": {
    "email": "alice@gmail.com",
    "plugin": "gmail"
  }
}

---

Stockage des connexions

Les connexions OAuth sont stockées par application :

conf/users/{app_id}.json      — métadonnées (email, plugin, user_id)
conf/tokens/{app_id}.json     — tokens chiffrés (Fernet, non lisibles sans clé)

Les tokens bruts ne sont jamais exposés dans l'API ni dans le portail.