L’API d’Elium utilise OAuth 2.0. Chaque appel se fait au nom d’un compte utilisateur. Votre programme obtient un jeton d’accès pour ce compte et l’envoie avec chaque requête :

Authorization: Bearer kp-oauth2-IrZ30CY27BBG8hryQOAvWVQ1isX1Na

Avant de commencer

Enregistrez votre programme comme application connectée, dans "Paramètres" > "Avancé" > "Applications connectées". Vous obtenez un identifiant client et un secret client, et vous déclarez les URL de redirection vers lesquelles le programme peut renvoyer les utilisateurs. API et applications connectées décrit chaque option.

Cochez le droit "API". Dans les requêtes, son nom est apiv1, et il couvre toute l’API : tout ce que l’utilisateur peut faire dans Elium, votre programme peut le faire aussi. Les deux droits MCP sont réservés aux assistants IA et ne donnent pas accès à l’API.

Une application marquée "De confiance" n’affiche pas l’écran d’approbation. Réservez cette option aux programmes que votre organisation contrôle, comme une intégration interne.

La plateforme publie sa configuration OAuth à l’adresse standard. Une bibliothèque OAuth peut donc se configurer avec la seule adresse de la plateforme :

https://nom-de-votre-plateforme.elium.com/.well-known/oauth-authorization-server

Authorization code

Ce flux est celui d’une application qui agit au nom d’utilisateurs, chacun connecté avec son propre compte. L’utilisateur approuve votre application dans son navigateur, et votre application échange le code obtenu contre des jetons.

Utilisez PKCE (Proof Key for Code Exchange, RFC 7636) sur ce flux. Elium l’accepte pour toute application et l’impose aux applications sans secret client. Votre application crée un code_verifier aléatoire, envoie son empreinte SHA-256 comme code_challenge, puis prouve qu’elle détient ce code_verifier au moment de demander le jeton. Toute bibliothèque OAuth le fait pour vous.

Redirigez le navigateur de l’utilisateur vers l’adresse d’autorisation avec ces paramètres :

https://nom-de-votre-plateforme.elium.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://myapplication.example/oauth2
  &scope=apiv1
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &state=A_RANDOM_VALUE

L’utilisateur se connecte à Elium si nécessaire et voit l’écran d’approbation. Pour une application de confiance, cet écran n’apparaît pas.

Si l’utilisateur accepte, Elium redirige le navigateur vers votre URL de redirection avec un paramètre code :
```
https://myapplication.example/oauth2?code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq&state=A_RANDOM_VALUE
```

Depuis son serveur, votre application échange le code contre des jetons :

curl --request POST \
  --data "grant_type=authorization_code" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq" \
  --data "code_verifier=YOUR_CODE_VERIFIER" \
  --data "redirect_uri=https://myapplication.example/oauth2" \
  https://nom-de-votre-plateforme.elium.com/oauth/token

La réponse est un document JSON avec le jeton d’accès, sa durée de vie en secondes et un jeton de rafraîchissement :

{
  "access_token": "kp-oauth2-IrZ30CY27BBG8hryQOAvWVQ1isX1Na",
  "token_type": "Bearer",
  "expires_in": 864000,
  "refresh_token": "kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq",
  "scope": "apiv1"
}

Password

Ce flux est celui d’un script ou d’une tâche de fond qui s’exécute sans intervention humaine. Le programme se connecte avec un nom d’utilisateur et un mot de passe et obtient directement des jetons.

Créez-lui un compte utilisateur dédié, avec un nom qui indique son usage, un mot de passe fort et seulement les droits nécessaires à la tâche. N’utilisez pas le compte d’une personne.

curl --request POST \
  --data "grant_type=password" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "username=api-sync" \
  --data "password=THE_ACCOUNT_PASSWORD" \
  https://nom-de-votre-plateforme.elium.com/oauth/token

La réponse a la même forme que pour le flux authorization code.

Renouveler le jeton d’accès

Le jeton d’accès expire après le nombre de secondes indiqué dans expires_in. Passé ce délai, l’API répond par une erreur d’authentification. Demandez-en un nouveau avec le jeton de rafraîchissement :

curl --request POST \
  --data "grant_type=refresh_token" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "refresh_token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq" \
  https://nom-de-votre-plateforme.elium.com/oauth/token

Si le jeton d’accès a expiré ou arrive à expiration, vous recevez un nouveau jeton d’accès et un nouveau jeton de rafraîchissement, et l’ancienne paire cesse de fonctionner. Sinon, vous recevez les mêmes jetons, avec leur durée de vie restante. Conservez toujours les jetons de la dernière réponse.

{
  "access_token": "kp-oauth2-DX5GlUVeLgjD4zUaOkpXtinj7AOhZb",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "kp-oauth2-0jTuX4wknsSlkoqRcrSTRyslzqw79f",
  "scope": "apiv1"
}

Révoquer un jeton

Pour révoquer un jeton d’accès ou un jeton de rafraîchissement, envoyez-le à l’adresse de révocation :

curl --request POST \
  --data "token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  https://nom-de-votre-plateforme.elium.com/oauth/revoke

Révoquer l’un des deux jetons révoque aussi l’autre.

Les utilisateurs peuvent aussi révoquer une application eux-mêmes, dans "Paramètres" > "Applications autorisées", et un administrateur système peut supprimer l’application pour tout le monde. Les deux procédures sont décrites dans API et applications connectées.