Bouton à intégrer pour initier
la connexion avec HelloAsso

Workflow

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

Présenter HelloAsso
Initier la mire de connexion dans une pop-up
Récupérer l'authorization_code issue de la liaison
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:

Nom du paramètre	Description	Exemple	Obligatoire
client_id	Votre client id.		Obligatoire
redirect_uri	L'URL sur laquelle l'utilisateur sera redirigé après la connexion. (succès ou échec), elle doit être url encode. (exemple : https%3A%2F%2Fwww.url.com%0A )	https://partenaire.com/success	Obligatoire
code_challenge	Voir ci-dessous.		Obligatoire
code_challenge_method	Méthode à utilisée. Doit être: `S256`	S256	Obligatoire
state	Une chaîne de texte de moins de 500 caractères. Cette valeur vous sera renvoyée à l'identique lors du callback. Elle peut être utilisé pour vérifier l'authenticité de la connexion et éviter des appels frauduleux ou pour encoder tout autres données.

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

Key	Value
content-type	application/x-www-form-urlencoded

Body

Key	Value	Obligatoire
client_id	Votre client ID	Obligatoire
client_secret	Votre client secret	Obligatoire
grant_type	"authorization_code"	Obligatoire
code	L'`authorization_code` reçu précédemment.	Obligatoire
code_verifier	La chaîne de caractère que vous avez généré aléatoirement, avant encodage.	Obligatoire
redirect_uri	L'url configuré précédemment (quand elle était dans l'URL elle devait être url_encode, ici elle ne doit pas l'être)	Obligatoire

Resultat (JSON)

Key	Description
access_token	Le token d'accès à utiliser pour vos futures appels.
refresh_token	Le token permettant de rafraichir le token d'accès après que celui-ci soit expiré.
token_type	"bearer"
expires_in	La durée de validité du token d'accès en seconde.
organization_slug	Le nom standardisé de l'association liée.

📘
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.