Authentification et facturation

Inférence compatible OpenAI, par clé API — facturée à l'organisation ou à l'utilisateur.

L'API d'inférence expose les modèles et les agents Oreus derrière les mêmes chemins que l'API OpenAI : /models, /chat/completions, /embeddings, /files. Le SDK OpenAI officiel fonctionne tel quel, il suffit de lui donner la bonne baseURL :

https://<hôte>/api/v1/external/inference

Elle ne s'authentifie pas comme l'API Third-Party : ici, c'est une clé API qui ouvre la porte, et un jeton utilisateur, optionnel, qui décide de qui paie.

Authentification

La clé API — obligatoire

Authorization: Bearer <clé API>

C'est une clé d'organisation, créée depuis la console Oreus ou via les routes Clés API de l'API Third-Party. Ce n'est pas le jeton OIDC : un JWT à cet endroit répond 401 API_KEY_INVALID.

Il en existe deux types, et le type décide de ce que model accepte :

Clé	`model`	Corps de requête
Model key	identifiant d'un modèle de la clé	100 % compatible OpenAI, transmis tel quel au fournisseur
Agent key	identifiant d'un agent de la clé	limité à `messages`, `model`, `stream` et `files` — le reste vient de la configuration de l'agent

GET /models liste ce que la clé donne accès à : des modèles pour une model key, des agents pour une agent key. Les embeddings ne sont disponibles qu'avec une model key.

Le jeton utilisateur — optionnel

x-oreus-user-authorization: Bearer <JWT d'organisation>

C'est le jeton d'organisation d'un utilisateur connecté à votre application en OIDC — le même que celui de l'API Third-Party. Présent, il bascule la facturation de l'organisation vers cet utilisateur.

Qui paie ?

En-têtes envoyés	Mode	Débité sur
`Authorization` seul	`ORGANIZATION`	l'organisation propriétaire de la clé
`Authorization` + `x-oreus-user-authorization`	`USER`	les orbs de l'utilisateur porté par le jeton

Le cas d'usage du mode USER : une application third-party qui connecte ses utilisateurs en OIDC et leur donne accès à des modèles ou des agents. Chaque appel est alors débité à l'utilisateur qui l'a déclenché, pas à l'application.

Le décompte se fait en deux temps : avant l'appel, une estimation (environ un token pour quatre caractères de prompt) sert à vérifier que le solde suffit ; après, c'est le usage réel renvoyé par le modèle qui est débité — en fin de flux pour une réponse en streaming.

Pour être accepté, le jeton utilisateur doit remplir toutes ces conditions — sinon la requête est refusée, elle n'est jamais rabattue sur l'organisation :

Condition	Sinon
JWT valide (signature, `iss`, `aud`, `exp`)	`401 USER_TOKEN_INVALID`
Émis pour une application third-party (`client_id`)	`403 USER_TOKEN_HAS_NO_CLIENT` / `USER_TOKEN_NOT_ISSUED_TO_A_THIRD_PARTY_APPLICATION`
Porte le scope `write:inference` (ou `read:inference` pour `/models`)	`403 USER_TOKEN_MISSING_INFERENCE_SCOPE`
Porte un contexte d'organisation (`organization_id`)	`403 USER_TOKEN_MISSING_ORGANIZATION`
L'application qui l'a émis appartient à l'organisation propriétaire de la clé	`403 API_KEY_NOT_OWNED_BY_APPLICATION_ORGANIZATION`
L'utilisateur a encore des orbs	`429 TIER_TOKEN_LIMIT_REACHED`

Les scopes read:inference et write:inference doivent être déclarés dans les permissions de votre application et demandés à la connexion, comme les autres scopes de ressource API. Omis, ils sont ignorés en silence — voir Configuration.

Exemple

Avec le SDK OpenAI, le jeton utilisateur se passe en en-tête par défaut :

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://<hôte>/api/v1/external/inference',
  apiKey: process.env.OREUS_API_KEY,
  // Optionnel : facture l'utilisateur plutôt que l'organisation.
  defaultHeaders: {
    'x-oreus-user-authorization': `Bearer ${organizationToken}`,
  },
});

const completion = await client.chat.completions.create({
  model: 'model-id', // ou l'identifiant d'un agent avec une agent key
  messages: [{ role: 'user', content: 'Bonjour !' }],
});

La même requête en cURL :

curl https://<hôte>/api/v1/external/inference/chat/completions \
  -H "Authorization: Bearer $OREUS_API_KEY" \
  -H "x-oreus-user-authorization: Bearer $ORGANIZATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-id","messages":[{"role":"user","content":"Bonjour !"}]}'

stream: true renvoie des server-sent events au format OpenAI, jusqu'au data: [DONE] final.

Guides

Démarrage rapide — de la clé API à la première réponse.
Streaming — le flux d'événements, le usage, les erreurs en cours de route.
Fichiers — envoyer un document ou une image et le joindre à un message.
Erreurs — chaque code, et lequel des deux jetons est en cause.

Les routes

Chaque route est documentée ci-après avec ses schémas et des exemples dans sept langages. La référence est générée depuis la spécification OpenAPI servie par le backend — elle ne peut donc pas diverger du code.