Vue d'ensemble
Connecter votre application à Oreus, et appeler ses API au nom de vos utilisateurs ou de votre organisation.
Oreus est une plateforme à part entière. Le programme d'applications tierces ouvre aux utilisateurs d'Oreus la possibilité de connecter leur application aux fonctionnalités de la plateforme : l'application s'y connecte en OpenID Connect, obtient un jeton au nom de l'utilisateur, puis appelle l'API Oreus avec ce jeton.
Chaque utilisateur qui accède à une application tierce doit avoir un compte Oreus et un abonnement à cette application, qu'elle soit gratuite ou payante.
Deux API, deux jetons
L'API regroupe deux familles de routes, qui ne s'authentifient pas de la même façon :
| API Third-Party | API Inférence | |
|---|---|---|
| Pour | agir au nom d'un utilisateur : organisations, agents, orbs, Vox, sessions, fichiers… | appeler des modèles et des agents, compatible OpenAI |
Authorization | JWT d'organisation de l'utilisateur (OIDC) | clé API de l'organisation |
| Permissions | un scope par route | — |
| Facturé à | l'utilisateur, pour les routes qui consomment des orbs | l'organisation ; ou l'utilisateur, si son JWT est joint en x-oreus-user-authorization |
| Guide | ci-dessous, puis Démarrage rapide | Inférence |
Les deux se combinent : une application qui connecte ses utilisateurs en OIDC peut réutiliser leur jeton d'organisation sur l'API d'inférence, pour que chaque appel soit débité à l'utilisateur plutôt qu'à l'application.
Les trois étapes
Se connecter
L'utilisateur est redirigé vers Oreus, s'authentifie, et accorde les
permissions demandées sur un écran de consentement. L'application récupère un
access_token, un id_token et un refresh_token.
Obtenir un jeton d'organisation
L'access token initial ne suffit pas pour l'API : celle-ci attend un jeton
porté par une organisation. On l'échange contre le refresh token, en
précisant organization_id.
Appeler l'API
Le JWT d'organisation part dans l'en-tête Authorization. L'API vérifie sa
signature contre le JWKS d'Oreus, puis iss,
aud et exp. Chaque route exige un scope, indiqué en tête de sa page dans
la référence.
Guides
- Démarrage rapide — de l'application déclarée au premier appel.
- Connexion — le flow OIDC en détail, les endpoints, la configuration.
- Inférence — clé API, facturation, streaming, fichiers.
- Scopes — chaque permission et les routes qu'elle ouvre.
- Conventions — pagination, tri, formats.
- Erreurs — chaque code, et quoi vérifier.
- Référence API — toutes les routes, avec leurs schémas et des exemples.
Ce qui change selon le type de client
Deux modèles coexistent, et ils ne se valent pas.
| Client public | Client confidentiel | |
|---|---|---|
| Exemples | web, iOS, Android | backend |
| Secret | aucun | client_secret |
| Protection du code | PKCE S256 | secret (+ PKCE) |
| Où vivent les jetons | dans le client | côté serveur |
Un client public ne peut rien garder de secret : son code est lisible, ses jetons sont à portée du navigateur ou du système. PKCE existe précisément pour combler ce trou. Un backend, lui, garde le secret et les jetons — le navigateur n'y reçoit qu'un cookie de session opaque.
Chaque route third-party attend le JWT d'organisation dans l'en-tête
Authorization, celui obtenu à l'étape 2. Un access token issu du flow ne
suffit pas.