---
updatedAt: 2026-03-19T15:28:14.000Z
agentTools:
  projectIndex: https://dev.helloasso.com/llms.txt
---

# API Overview

Complete overview of the HelloAsso API — authentication, Checkout integration, and all available endpoints.

<Callout icon="👋" theme="default">
  **This is only a brief overview of the API documentation. Please refer to the sections in the left-hand menu for more detailed explanations.**
</Callout>

# API Overview

This page provides a complete summary of the HelloAsso API v5 and Plus Billetterie API, including authentication, Checkout integration, and all available endpoints.

## Base URLs

| Environment    | API Base URL                           | Website                                                    |
| -------------- | -------------------------------------- | ---------------------------------------------------------- |
| **Production** | `https://api.helloasso.com/v5`         | [helloasso.com](https://www.helloasso.com)                 |
| **Sandbox**    | `https://api.helloasso-sandbox.com/v5` | [helloasso-sandbox.com](https://www.helloasso-sandbox.com) |

<Callout icon="🧪" theme="info">
  Use the sandbox environment to test your integration. Create an organization at [helloasso-sandbox.com](https://www.helloasso-sandbox.com), then retrieve your API client from the back office. Virtual credit cards are available for testing payments.
</Callout>

***

## Authentication (OAuth 2.0)

The HelloAsso API uses [OAuth 2.0](https://tools.ietf.org/html/rfc6749) for authentication. You need an API client (ID and Secret) to get started.

### Getting your API credentials

* **Organizations (associations):** Obtain your client ID and secret from your administration area. You receive these privileges: `AccessPublicData`, `AccessTransactions`, and `Checkout`.
* **Partners:** Contact HelloAsso at <partenariats@helloasso.org> to obtain a client.

<Callout icon="🔒" theme="warning">
  Keep your client ID and secret confidential. Never expose them in client-side code or public repositories.
</Callout>

### Supported grant types

<Tabs>
  <Tab title="Client Credentials">
    Use `grant_type=client_credentials` to authenticate directly with your client ID and secret.

    * **Organizations:** Access is limited to the organization the client was issued to.
    * **Partners:** Does not grant any User Roles on organization resources. You can only access routes that don't require a User Role.

    ```bash title="Request"
    curl -X POST https://api.helloasso.com/oauth2/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET"
    ```

    ```json title="Response"
    {
      "access_token": "eyJhbGciOiJSUzI1NiIs...",
      "refresh_token": "UxMiwiZX...",
      "token_type": "bearer",
      "expires_in": "1800"
    }
    ```
  </Tab>

  <Tab title="Refresh Token">
    Use `grant_type=refresh_token` to obtain a new access token using a previously issued refresh token.

    Once you have an access token and a refresh token, you **must** use the refresh token to obtain a new access token. Do **not** re-authenticate with your client credentials.

    ```bash title="Request"
    curl -X POST https://api.helloasso.com/oauth2/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=refresh_token" \
      -d "refresh_token=YOUR_REFRESH_TOKEN"
    ```

    ```json title="Response"
    {
      "access_token": "eyJhbGciOiJSUzI1NiIs...",
      "refresh_token": "NEW_REFRESH_TOKEN...",
      "token_type": "bearer",
      "expires_in": "1800"
    }
    ```
  </Tab>

  <Tab title="Authorization Code">
    Use `grant_type=authorization_code` (**partners only**) to access private resources of organizations through the authorization flow. This requires the user to grant permission via a consent screen.
  </Tab>
</Tabs>

### Token lifecycle

| Token           | Lifetime   | Notes                                                                |
| --------------- | ---------- | -------------------------------------------------------------------- |
| `access_token`  | 30 minutes | Short-lived JWT, include in the `Authorization: Bearer TOKEN` header |
| `refresh_token` | 1 month    | Use it to get a new access token + refresh token pair                |

Each time you refresh, you receive a new `access_token` (valid 30 min) and a new `refresh_token` (valid 1 month). By continuously using each refresh token, you can stay authenticated indefinitely without re-entering credentials.

***

## Checkout Integration

The Checkout allows contributors to make payments through a form pre-filled by a partner or organization.

### How it works

1. **Create a checkout intent** — `POST /organizations/{organizationSlug}/checkout-intents` with contributor information, payment terms, and redirect URLs.
2. **Redirect the contributor** — The response contains a `redirectUrl` (valid for 15 minutes). Redirect the contributor to this URL to complete payment.
3. **Contributor pays** — The contributor validates the form and pays.
4. **Handle the redirect** — The contributor is redirected to your `returnUrl` with a result parameter (`success`, `error`, etc.).
5. **Receive notifications** — Configure webhook notifications for Order and Payment events.
6. **Verify the result** — `GET /organizations/{organizationSlug}/checkout-intents/{checkoutIntentId}` to retrieve the checkout intent result and created order.

### Required fields for checkout intent

| Field              | Type    | Description                                                          |
| ------------------ | ------- | -------------------------------------------------------------------- |
| `totalAmount`      | integer | Total amount in **cents** (must equal initial amount + sum of terms) |
| `initialAmount`    | integer | First payment amount in **cents**                                    |
| `itemName`         | string  | Description of what the contributor is paying for (max 250 chars)    |
| `backUrl`          | string  | URL if the contributor wants to go back                              |
| `errorUrl`         | string  | URL called on checkout error                                         |
| `returnUrl`        | string  | URL called after payment                                             |
| `containsDonation` | boolean | Whether the payment (or part of it) is a donation                    |

### Optional fields

| Field                       | Type    | Description                                                    |
| --------------------------- | ------- | -------------------------------------------------------------- |
| `terms`                     | array   | List of future payment terms (amount in cents + date)          |
| `payer`                     | object  | Pre-fill payer info: firstName, lastName, email, address, etc. |
| `metadata`                  | object  | Custom JSON metadata (max 20,000 chars)                        |
| `paymentOptions.enableSepa` | boolean | Enable SEPA payment for this checkout                          |

## HelloAsso API v5 — Endpoints

All endpoints below use the base URL `https://api.helloasso.com/v5` and require OAuth 2.0 authentication.

Please go to the [API Reference](https://dev.helloasso.com/update/reference) section.