> For the complete documentation index, see [llms.txt](https://help.steeple.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.steeple.com/administration/api-steeple.md).

# Comment utiliser l'API Steeple ?

## Présentation

L'API Steeple permet à vos outils internes (SIRH, intranet, outil de BI…) d'échanger des données avec votre organisation Steeple, sans passer par l'interface.

Elle est accessible à l'adresse `https://api.steeple.com`. La référence complète des endpoints, avec leurs paramètres et leurs réponses, est publiée sur [https://api-docs.steeple.com](https://api-docs.steeple.com/).

## Ce que l'API permet

| Besoin                                             | Endpoints                                                                              | Accès    |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- | -------- |
| Créer, mettre à jour ou retirer des collaborateurs | `POST /v1/blobs`, `POST /v1/member_provisionings`, `GET /v1/member_provisionings/{id}` | Écriture |
| Lister les collaborateurs de l'organisation        | `GET /v1/users`                                                                        | Lecture  |
| Lister les communautés de l'organisation           | `GET /v1/communities`                                                                  | Lecture  |
| Lister les publications                            | `GET /v1/posts`                                                                        | Lecture  |
| Consulter les statistiques d'une publication       | `GET /v1/posts/{id}/statistics`                                                        | Lecture  |

L'écriture porte uniquement sur les collaborateurs, par import de fichier : voir [Comment synchroniser mon annuaire de collaborateurs avec l'API Steeple ?](https://help.steeple.com/administration/synchroniser-annuaire-api.md).

La création de publications ou de documents n'est pas disponible par l'API.

## Prérequis

* Être administrateur de l'organisation.

## Étape 1 — Générer un token

Rendez-vous dans l'**Administration**, section **Intégrations** (`/administration/integrations`), puis sélectionnez **API Steeple**.

Cliquez sur **Générer un token** et renseignez :

* **Nom** : l'outil qui utilisera le token, par exemple « SIRH ».
* **Description** : l'usage prévu, pour vous y retrouver plus tard.

Le token s'affiche **une seule fois**. Copiez-le et conservez-le en lieu sûr avant de fermer la fenêtre : il ne sera plus possible de le récupérer. En cas de perte, générez-en un nouveau et révoquez l'ancien.

Créez un token par outil : vous pourrez ainsi couper l'accès d'un outil sans toucher aux autres.

## Étape 2 — Appeler l'API

Chaque appel porte le token dans l'en-tête `Authorization` :

```bash
curl "https://api.steeple.com/v1/communities" \
  -H "Authorization: Bearer <votre token>"
```

Un token donne accès aux données de **toute l'organisation**. Il ne correspond à aucun collaborateur en particulier.

Les listes sont paginées avec les paramètres `page` (à partir de 1) et `per_page` (20 par défaut, 50 au maximum).

## Révoquer un token

Dans **Intégrations** > **API Steeple**, cliquez sur **Révoquer** en face du token. Les appels faits avec ce token sont refusés immédiatement.

Un token n'a pas de date d'expiration : il reste valable tant qu'il n'est pas révoqué. Traitez-le comme un mot de passe et révoquez-le dès qu'il a pu être exposé.

## Ce que l'assistant peut faire

L'assistant peut guider l'utilisateur vers la page **Intégrations** via navigate\_to et expliquer ce que l'API permet (lecture des collaborateurs, communautés et publications, import de collaborateurs). Il ne peut pas générer ni révoquer de token. Pour le détail des endpoints, orienter vers <https://api-docs.steeple.com>.
