Authentification & sécurité

Le flux d'authentification d'une app tierce est conçu pour ouvrir une app frontend externe au nom d'un utilisateur Superfasttt, sans exposer le jeton utilisateur à cette app.

Il repose sur deux jetons :

1. launch_token : jeton court, à usage unique, transmis dans l'URL de lancement de votre app.
2. access_token app : jeton Bearer court obtenu par votre frontend en échangeant le launch_token. Il sert ensuite aux appels API de votre app.

Vue d'ensemble

[Utilisateur Superfasttt]          [Votre frontend]              [API Superfasttt]
        │
        │  Ouvre votre app
        │  URL: entry_url?launch_token=...
        │ ───────────────────────────────►
        │
        │                                │  POST /api/v1/app-platform/runtime/exchange
        │                                │  body: { launch_token }
        │                                │ ───────────────────────────────►
        │                                │
        │                                │  { access_token, expires_in, scopes }
        │                                │ ◄───────────────────────────────
        │
        │                                │  Authorization: Bearer <access_token>
        │                                │  /api/v1/app-data/...
        │                                │  /api/v1/rich-documents/...
        │                                │  /api/v1/app-assets/...

Règles du launch_token

• Il est généré par Superfasttt pour ouvrir une app installée.
• Il expire rapidement.
• Il ne peut être utilisé qu'une seule fois.
• Il doit être échangé immédiatement par le frontend de votre app.
• Après l'échange, retirez launch_token de l'URL avec window.history.replaceState.

Ne stockez pas le launch_token. Ne le transmettez pas à des services tiers.

Échanger le launch_token

const launchToken = new URL(window.location.href).searchParams.get("launch_token");

const response = await fetch(
  "https://api.superfasttt.ai/api/v1/app-platform/runtime/exchange",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ launch_token: launchToken }),
  }
);

if (!response.ok) {
  throw new Error(`Exchange failed: ${response.status}`);
}

const session = await response.json();

Réponse :

{
  "access_token": "<app_access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scopes": ["app_data:read", "app_data:write"]
}

Utiliser l'access_token app

await fetch("https://api.superfasttt.ai/api/v1/app-data/inspections/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${session.access_token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ page: 1, page_size: 50 })
});

L'access_token app est limité :

• à l'app installée,
• à l'utilisateur qui l'a ouvert,
• aux permissions accordées,
• aux origins autorisées,
• à une durée courte.

Gardez-le en mémoire lorsque c'est possible. Évitez de le conserver durablement dans le navigateur.

Origins autorisées

Le manifest déclare les origins depuis lesquelles votre frontend peut appeler l'API :

"runtime": {
  "type": "external",
  "entry_url": "https://audit-pro.example.com",
  "allowed_origins": ["https://audit-pro.example.com"]
}

L'origin doit correspondre exactement à celle envoyée par le navigateur :

• https://audit-pro.example.com et https://www.audit-pro.example.com sont deux origins différentes.
• http://localhost:3000 et http://localhost:3001 sont deux origins différentes.
• Les chemins ne font pas partie de l'origin. Déclarez https://audit-pro.example.com, pas https://audit-pro.example.com/app.

Pour tester avec curl, ajoutez explicitement le header Origin :

curl -X POST https://api.superfasttt.ai/api/v1/app-platform/runtime/exchange \
  -H "Content-Type: application/json" \
  -H "Origin: https://audit-pro.example.com" \
  -d '{"launch_token":"<launch_token>"}'

Scopes

Les scopes renvoyés à l'échange correspondent aux permissions accordées à l'installation.

Si une route retourne 403 missing_scope, ajoutez la permission nécessaire au manifest, réimportez-le et réinstallez l'app.

Renouvellement de session

Il n'y a pas de refresh token dans le flux navigateur. Quand l'access_token expire, l'utilisateur doit relancer l'app depuis Superfasttt pour obtenir un nouveau launch_token, puis un nouvel access_token.

Pour une intégration serveur à serveur ou une tâche longue, contactez Superfasttt afin de définir le mode d'authentification approprié.

Bonnes pratiques frontend

• Échangez le launch_token dès le chargement de la page.
• Supprimez launch_token de l'URL après l'échange.
• Gardez l'access_token en mémoire plutôt que dans un stockage persistant.
• N'envoyez jamais l'access_token à un domaine qui ne vous appartient pas.
• Gérez proprement les expirations en proposant de rouvrir l'app.
• Déclarez séparément les origins de production, staging et développement.

Erreurs fréquentes