Applications OAuth 2.0

Vous développez une application que d'autres sociétés Pennylane pourront installer ? Pennylane prend en charge le flux standard d'autorisation par code. Demandez d'abord à Pennylane des identifiants partenaire (clientId, clientSecret).

Le flux

<?php

use Pennylane\Sdk\OAuth\OAuthApp;

$app = new OAuthApp(
    clientId: '...',
    clientSecret: '...',
    redirectUri: 'https://yourapp.example.com/oauth/callback',
);

// 1. Envoyer l'utilisateur vers l'écran de consentement Pennylane
$url = $app->authorizationUrl(
    scopes: ['customer_invoices:all', 'customers:all'],
    state: $antiCsrfToken,
);

// 2. Pennylane redirige avec ?code=... ; échanger ce code
$tokens = $app->exchangeCode($code);

// 3. Utiliser le jeton d'accès comme un jeton API classique
use Pennylane\Sdk\Pennylane;

$client = new Pennylane(apiToken: $tokens->accessToken);

Durée de vie du jeton et rafraîchissement

Les jetons d'accès vivent 24 heures ($tokens->expiresIn === 86400). Rafraîchissez-les avant expiration :

$newTokens = $app->refresh($storedRefreshToken);
save($newTokens->accessToken, $newTokens->refreshToken); // à persister IMMÉDIATEMENT

Rotation du refresh token

Pennylane fait tourner les refresh tokens : chaque rafraîchissement invalide les deux jetons précédents. Deux règles en découlent :

1. Ne jamais lancer deux rafraîchissements en parallèle pour la même connexion. OAuthApp ne sérialise pas les appels pour vous : si deux requêtes tentent de rafraîchir le même jeton stocké en même temps, l'une d'elles présentera un refresh token déjà remplacé par la rotation et échouera. Protégez le rafraîchissement avec votre propre verrou (verrou de ligne en base de données, mutex distribué, etc.), que ce soit au sein d'un même processus ou entre plusieurs.
2. Persister la nouvelle paire avant de l'utiliser. Si vous plantez après le rafraîchissement mais avant la sauvegarde, le refresh token stocké est mort et l'utilisateur doit se réauthentifier.

Quand un refresh token est invalide (révoqué, remplacé par la rotation, expiré), l'endpoint de jeton répond 401 invalid_grant et le SDK lève une AuthenticationException : faites repasser l'utilisateur par le flux d'autorisation.

La migration des scopes 2026

En janvier 2026, Pennylane a remplacé le scope historique ledger par des scopes granulaires et a automatiquement ajouté les nouveaux scopes aux applications OAuth existantes. Si votre application a été créée avant cette date, réauthentifier vos utilisateurs une fois permet d'aligner leurs consentements sur le nouveau modèle de scopes.