Workflow

Afin de lier votre client_id avec une association, il vous faut passer par 4 étapes:

1. Présenter HelloAsso
2. Initier la mire de connexion dans une pop-up
3. Récupérer l'authorization_code issue de la liaison
4. L'échanger contre un access_token et unrefresh_token afin de faire vos appels sur les données de l'asso.

A noter que lors d'une mire de connexion, vous liez votre client_id à l'entité "association" et non à la personnes qui a initié la mire.

1. Présenter HelloAsso

Lorsque vous implémentez une connexion à HelloAsso via l’API dans un outil pour les associations, il est essentiel que celles-ci puissent identifier HelloAsso et son modèle économique, afin qu’elles puissent communiquer sur ce sujet à leurs publics et ainsi, éviter toute incompréhension ou friction.

🤝

Texte à intégrer dans le parcours de l'association pour sa connexion avec HelloAsso

HelloAsso aide les associations à collecter des paiements en ligne et propose ses services gratuitement. Elle prend à sa charge tous les frais de transaction pour que vous puissiez bénéficier de la totalité des sommes versées par vos publics, sans frais. Les contributions volontaires laissées par ces derniers sont leur unique source de revenus.

2. Enregistrement de votre domaine de redirection

Afin de sécuriser le processus de mire d'autorisation, vous ne pouvez l'initier que depuis le domaine que vous avez configuré pour votre clé.

Utilisez le end-point à votre disposition pour modifier votre domaine.

3. Initier la mire de connexion

Pour obtenir un authorization_code, vous devez initier une mire de connexion dans une pop-up lorsque l'utilisateur clique sur le bouton de connexion.

L'url de la pop-up doit être la suivante:

https://auth.helloasso.com/authorize

Vous devez également ajouter les paramètres d'URL suivants:

URL de redirection

L'URL de redirection doit être en https obligatoirement.

Le domaine de l’URL de redirection doit être le même que celui configuré pour votre client API.

📘

Enregistrement de votre domaine de redirection

Utilisez le end-point à votre disposition pour modifier votre domaine vous même.

Code challenge

PKCE (Proof Key for Code Exchange) est une mesure de sécurité pour l'octroi de l'autorisation.

Etant un standard, il existe sur internet nombre de librairies open-source qui permettent de générer un code challenge PKCE.

Si vous souhaitez le faire vous même voici la marche à suivre:

• Vous devez générer une chaine de texte aléatoire de 43 à 128 caractères, parmi les caractères suivants : ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.\_~
• Vous devez ensuite générer le Code Challenge :
  • hachez-la chaîne de texte précédemment obtenu avec la fonction de hachage SHA-256
  • encodez-la en base64
  • encodez-la par URL

Gardez la chaîne générée précieusement, elle sera utile pour échanger l'authorization_code contre un access_token.

📘

Tester votre générateur de code challenge

Si vous souhaitez tester votre générateur de challenge de code, vous pouvez le faire ici
avec cet outil en ligne : https://tonyxu-io.github.io/pkce-generator/

Exemple

https://auth.helloasso.com/authorize?client_id=9fdc22226bf24ff99b875f4a7c503715&redirect_uri=YOUR_REDIRECT_URI&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256&state=abc

4. Récupérer l'authorization_code

Dans la popup, l'utilisateur a la possibilité de sélectionner l'association qu'il souhaite lier.

S'il n'en a pas déjà une, il peut la créer une directement depuis la popup en cliquant sur "Vous n'avez pas encore de compte ?", suite de son inscription il sera redirigé sur la mire d'autorisation pour terminer le processus de liaison.

Lorsque l'utilisateur termine le processus, il sera redirigé sur la redirect_uri défini précédemment.

Nous ajoutons un paramètre d'URL

• codeayant pour valeur l'authorization_code
• statesi celui-ci a été renseigné

Dans le cas ou une erreur est apparue, le code erreur sera transmis dans l'URL également.

Exemple

https://www.partenaire.com/success?code=xipPrCkrZ7DkAx9pzGYafMn39Zbfgc978j2cvHfmDaRGutn6zQKH4fE6ZXqVwVqHW35RYAbtSWGx95i3AQci52hQZ4pzF7ARC&state=abc

🚧

Validité de l'authorization_code

Attention, l'authorization_code n'est valable que 5min.

5. Échanger un authorization_code contre un access et refresh token

Enfin pour réaliser vos appels, vous pouvez maintenant échanger l'authorization_code contre un access_token en procédant à un appel POST sur l’URL:

https://api.helloasso.com/oauth2/token

🚧

Rôle de l'access_token issue de la liaison

L'access_token issue de la liaison aura le rôle organisation_admin sur l'association avec laquelle vous avez fait la liaison.

Header

Body

Resultat (JSON)

📘

Stockage du slug de l'association

C'est dans le résultat de cet appel que vous pouvez trouver le slug de l'association qui vient de ce lier.

Attention cependant: une association peut, exceptionnellement, changer de slug, pensez-donc à implémenter la réception de la notification de changement de slug.

Exemple

curl --location 'https://api.helloasso.com/oauth2/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'client_secret=xxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data-urlencode 'code=4xmNv7JZCb5zvzMknW3uQVeWPSDFN16f1h9ed1v9z1VqWa4n7b7uCdAaCPPMDsJxqt7ASmc3tgR35yZ7udzNdpmfh' \
--data-urlencode 'redirect_uri=https://www.partenaire.com/success' \
--data-urlencode 'code_verifier=8F2g_j-HYRQPBpaJCmSFKGGuW~2PRHB3xb.TxpRLDbwrlhB4F'

Temps de validité des tokens

Nous vous recommandons de suivre les guidelines d’implémentation du protocole OAuth, notamment sur la rotation automatique des access tokens (TTL: 30min) avec le refresh token (TTL: 30 jours) afin que la session utilisateur ne soit pas interrompue.

Les access_token et refresh_token issu d'une liaison avec la mire ne remplacent pas ceux que vous pouvez généré avec votre clé API partenaire. Ils doivent uniquement servir à récupérer des informations concernant l’association qui vient de se lier.

Le fait d'enregistrer ces tokens ainsi que leur date d’émission dans votre base de données vous permettra de connaître leur date d’expiration : 30 minutes pour l’access_token et 30 jours pour le refresh_token.

Si, au bout de trente jours, vous n’avez pas renouvelé ces tokens (voir la section « Rafraîchir un token »), ils expireront et la liaison avec l’association sera brisée. Il est donc nécessaire de prévoir un mécanisme automatique et régulier pour rafraîchir ces tokens.

Vous pouvez établir autant de liaisons que vous le souhaitez, et donc disposer de plusieurs tokens.