API — OAuth

Les endpoints OAuth gèrent la connexion des comptes Gmail et Microsoft 365 à vos applications SendAs.me.

GET /oauth/connect/{app_id}

Initie le flux OAuth pour une application. Retourne l'URL vers laquelle rediriger l'utilisateur pour qu'il s'authentifie.

Paramètres d'URL :

Paramètre	Type	Description
app_id	UUID	L'identifiant interne de l'application (pas le pushable_key)

Paramètres de requête :

Paramètre	Type	Obligatoire	Description
plugin	string	Oui	Plugin à connecter : gmail ou microsoft

Requête :

GET /oauth/connect/a1b2c3d4-e5f6-7890-abcd-ef1234567890?plugin=gmail
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=123456789.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fapi.sendas.me%2Foauth%2Fcallback%2Fgmail&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&access_type=offline&prompt=consent&state=csrf_state_token_abc123"
}

L'URL retournée contient :

• Le client_id Google ou Microsoft
• L'redirect_uri vers /oauth/callback/\{plugin\}
• Les scope nécessaires pour envoyer des e-mails
• access_type=offline pour obtenir un refresh token
• prompt=consent pour forcer l'affichage du consentement (nécessaire pour obtenir un refresh token si le compte est déjà autorisé)
• Le state anti-CSRF unique

Réponse 404 :

{
  "detail": "Application not found"
}

Réponse 400 :

{
  "detail": "Plugin 'gmail' non activé sur cette application"
}

Intégration dans une interface

Dans le portail, le bouton "Connecter Gmail" appelle cet endpoint et redirige l'utilisateur vers la redirect_url retournée. Dans votre propre interface, vous pouvez faire de même.

GET /oauth/callback/{plugin}

Endpoint de callback appelé automatiquement par Google ou Microsoft après que l'utilisateur a autorisé l'accès. Cet endpoint n'est pas destiné à être appelé directement.

Paramètres d'URL :

Paramètre	Type	Description
plugin	string	Plugin OAuth : gmail ou microsoft

Paramètres de requête (fournis par Google/Microsoft) :

Paramètre	Type	Description
code	string	Code d'autorisation unique, à usage unique
state	string	Token anti-CSRF (vérifié contre oauth_states en DB)
error	string	Présent en cas de refus de l'utilisateur

Flux interne :

1. Vérification du state dans oauth_states (anti-CSRF, TTL 10 min)
2. Échange du code contre access_token + refresh_token
3. Récupération de l'email du compte via l'API (userinfo ou MS Graph)
4. Chiffrement des tokens avec Fernet
5. Sauvegarde dans oauth_credentials
6. Suppression du state utilisé
7. Envoi du webhook oauth_connected
8. Redirection vers le portail avec un message de succès

Réponse en cas de succès : Redirection HTTP 302 vers le portail

Réponse en cas d'erreur : Redirection HTTP 302 vers le portail avec un paramètre d'erreur

DELETE /oauth/{credential_id}

Supprime un credential OAuth (déconnecte un compte Gmail ou Microsoft).

Requête :

DELETE /oauth/cred_xyz789abc
X-Api-Secret: votre_api_secret

Réponse 204 : (aucun corps)

Révocation côté Google/Microsoft

La suppression d'un credential OAuth dans SendAs.me ne révoque pas automatiquement les tokens côté Google ou Microsoft. Pour une déconnexion complète, l'utilisateur doit également révoquer l'accès depuis son compte Google ou Microsoft.

Stockage des credentials

Les credentials OAuth sont stockés par application dans des fichiers JSON individuels :

conf/users/{app_id}.json

Chaque fichier contient les tokens chiffrés (access token, refresh token) et les métadonnées du compte connecté pour l'application correspondante.

Ancien format

Avant cette version, tous les credentials étaient regroupés dans un fichier unique conf/smtp_users.json. Ce fichier n'est plus utilisé. Chaque application dispose désormais de son propre fichier isolé dans conf/users/.

---

Paramètre callback_url

Le paramètre callback_url permet à votre application de recevoir le résultat du flux OAuth directement, sans passer par le portail SendAs.me.

Utilisation

Ajoutez ?callback_url=https://your-app.com/done à l'URL de la page de connexion OAuth :

GET /oauth/connect/\{app_id\}?plugin=gmail&callback_url=https://your-app.com/done

En cas de succès

L'utilisateur est redirigé vers votre callback_url avec les paramètres suivants :

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

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

En cas d'échec

Une page d'erreur est affichée à l'utilisateur, avec un lien de retour vers votre callback_url.

Formats acceptés

Seules les URLs http:// et https:// sont acceptées. Toute autre valeur (ex : javascript:, data:, chemin relatif) est rejetée et le flux s'interrompt avec une erreur.

---

GET /oauth/credentials/{app_id}

Liste tous les credentials OAuth d'une application.

Requête :

GET /oauth/credentials/a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Api-Secret: votre_api_secret

Réponse 200 :

{
  "credentials": [
    {
      "id": "cred_xyz789abc",
      "app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "alice@gmail.com",
      "plugin": "gmail",
      "status": "active",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      "connected_at": "2024-01-10T09:00:00Z",
      "last_used_at": "2024-01-15T10:35:00Z",
      "expires_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "cred_abc456def",
      "app_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "bob@monentreprise.com",
      "plugin": "microsoft",
      "status": "active",
      "scopes": [
        "Mail.Send",
        "offline_access",
        "User.Read"
      ],
      "connected_at": "2024-01-12T11:00:00Z",
      "last_used_at": "2024-01-14T16:20:00Z",
      "expires_at": "2024-01-14T17:20:00Z"
    }
  ]
}

Statuts possibles

Statut	Description
active	Token valide, prêt à envoyer
expired	Access token expiré — sera rafraîchi automatiquement au prochain envoi
revoked	Révoqué par l'utilisateur — reconnexion manuelle nécessaire
error	Erreur lors du dernier refresh — investigation nécessaire