> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/publier/embedding/using-with-authenticated-docs.md).

# Authentification

Si votre documentation GitBook nécessite une authentification, Docs Embed a besoin d’un jeton visiteur GitBook pour accéder au contenu.

Il existe deux approches :

1. **Transmettez le jeton directement** (recommandé) - Initialisez l’intégration avec un jeton visiteur GitBook.
2. **Utiliser la détection basée sur les cookies** - Vérifiez la présence du jeton visiteur GitBook avant le chargement.

## Approche 1 : transmettre le jeton directement (recommandé)

Lors de l’initialisation de l’intégration, transmettez le jeton visiteur GitBook comme `visitor.token`.

`visitor.token` n’est pas un jeton d’accès brut ni un jeton ID provenant de votre fournisseur d’identité. Il s’agit du jeton visiteur GitBook que GitBook émet pour l’accès authentifié à la documentation. Le `your-jwt-token` valeurs dans ces exemples représentent ce jeton émis par GitBook.

{% tabs %}
{% tab title="Script autonome" %}

```html
<script src="https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token"></script>
<script>
  window.GitBook(
    "init",
    { siteURL: "https://docs.company.com" },
    { visitor: { token: "your-jwt-token" } }
  );
  window.GitBook("show");
</script>
```

{% endtab %}

{% tab title="Package NPM" %}

```javascript
import { createGitBook } from "@gitbook/embed";

const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});

const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: "your-jwt-token",
    unsignedClaims: { userId: "123", plan: "premium" },
  },
});
```

{% endtab %}

{% tab title="Composants React" %}

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    visitor={{
      token: "your-jwt-token",
      unsignedClaims: { userId: "123" },
    }}
  />
</GitBookProvider>
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
L’API de configuration de l’intégration n’a pas changé. Transmettez les jetons visiteur émis par GitBook comme `visitor.token`.

Pour les sites authentifiés, GitBook transmet ce jeton au site sous la forme `jwt_token` dans l’URL de l’iframe/du script. Si vous chargez le script autonome depuis un site authentifié, vous devez inclure `jwt_token` dans le `<script src>` URL.
{% endhint %}

## Sites basés sur OIDC

Docs Embed accepte le flux du jeton visiteur GitBook utilisant HS256. Vous ne pouvez pas modifier ni configurer cet algorithme pour accepter des jetons de fournisseur d’identité RS256.

Ne transmettez pas le jeton d’accès ou le jeton ID d’un fournisseur OIDC en tant que `visitor.token`. Les jetons Auth0 et Descope qui utilisent RS256 sont incompatibles et Docs Embed les rejette en raison de leur algorithme de signature. Ne faites pas transiter, ne resignez pas et ne créez pas de jeton visiteur GitBook à partir d’un jeton de fournisseur d’identité.

Pour un site de documentation basé sur OIDC, utilisez ce flux :

1. Envoyez l’utilisateur vers l’URL de votre site de documentation protégé, par exemple `https://docs.example.com`.
2. Effectuez la connexion OIDC interactive normale sur le site de documentation.
3. Après que GitBook a établi la session du site de documentation et stocké `gitbook-visitor-token`, récupérez ce jeton.
4. Transmettez le jeton avec l’approche basée sur les cookies ou l’approche par jeton direct sur cette page.

Ce flux nécessite une connexion préalable réussie au site de documentation. Il nécessite également le cookie requis et la disponibilité du domaine.

{% hint style="warning" %}
Docs Embed ne peut pas démarrer, rediriger ou terminer silencieusement la poignée de main d’autorisation OIDC du site de documentation. Si un visiteur authentifié pour la première fois a besoin d’un accès entièrement à l’intérieur de l’intégration, il n’existe aucun chemin d’intégration pris en charge. Faites-le passer par une étape explicite de connexion au site de documentation avant de charger l’intégration authentifiée.
{% endhint %}

## Approche 2 : détection basée sur les cookies

Si votre site de documentation stocke le jeton visiteur dans des cookies (comme `gitbook-visitor-token`), vous pouvez vérifier sa présence avant de charger l’intégration.

Après qu’un utilisateur se connecte à votre site de documentation authentifié, GitBook stocke un jeton visiteur dans les cookies de son navigateur sous la clé `gitbook-visitor-token`. L’intégration a besoin de ce jeton pour récupérer le contenu de votre documentation.

**Le flux :**

1. L’utilisateur se connecte à votre site de documentation.
2. GitBook stocke le jeton visiteur dans les cookies du navigateur.
3. Votre application vérifie la présence du jeton.
4. Si le jeton existe, chargez l’intégration et transmettez le jeton.
5. Si le jeton n’existe pas, envoyez l’utilisateur sur votre site de documentation pour se connecter.

{% tabs %}
{% tab title="Script autonome" %}
**Extrait à copier-coller**

Utilisez cet extrait uniquement après que l’utilisateur a terminé la connexion au site de documentation :

```html
<script>
  (function () {
    // Vérifier la présence du jeton visiteur dans les cookies
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      console.warn("[Docs Embed] Connectez-vous sur https://docs.example.com avant de charger l’intégration.");
      return;
    }

    // Le jeton existe, chargez l’intégration
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% hint style="warning" %}
Remplacer `docs.example.com` avec l’URL réelle de votre site de documentation.
{% endhint %}

**Autre solution : inviter les utilisateurs à se connecter**

Si le jeton est manquant, envoyez l’utilisateur vers l’URL protégée du site de documentation. Cela démarre le flux de connexion OIDC interactive pris en charge :

```html
<script>
  (function () {
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      // Rediriger vers la documentation ou afficher un message
      alert("Veuillez vous connecter à votre documentation pour accéder à l’aide.");
      window.location.href = "https://docs.example.com";
      return;
    }

    // Charger l’intégration avec le jeton
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% endtab %}

{% tab title="Package NPM" %}
Lorsque vous utilisez le package NPM, vérifiez la présence du jeton avant l’initialisation :

```javascript
import { createGitBook } from "@gitbook/embed";

function initializeEmbed() {
  // Vérifier la présence du jeton dans les cookies
  const getCookie = (name) => {
    const value = `; ${document.cookie}`;
    const parts = value.split(`; ${name}=`);
    if (parts.length === 2) return parts.pop().split(";").shift();
  };

  const token = getCookie("gitbook-visitor-token");

  if (!token) {
    console.warn("[Docs Embed] Connectez-vous au site de documentation avant de charger l’intégration.");
    return null;
  }

  const gitbook = createGitBook({
    siteURL: "https://docs.example.com",
  });

  const iframe = document.createElement("iframe");
  iframe.src = gitbook.getFrameURL({
    visitor: { token: token },
  });
  const frame = gitbook.createFrame(iframe);

  document.getElementById("embed-container").appendChild(iframe);
  return frame;
}

initializeEmbed();
```

{% endtab %}

{% tab title="Composants React" %}
Pour les applications React, affichez conditionnellement l’intégration après que la connexion au site de documentation a créé le jeton visiteur :

```jsx
import { useEffect, useState } from "react";
import { GitBookProvider, GitBookFrame } from "@gitbook/embed/react";

function App() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    // Vérifier la présence du jeton dans les cookies
    const getCookie = (name) => {
      const value = `; ${document.cookie}`;
      const parts = value.split(`; ${name}=`);
      if (parts.length === 2) return parts.pop().split(";").shift();
    };

    const visitorToken = getCookie("gitbook-visitor-token");
    setToken(visitorToken);
  }, []);

  if (!token) {
    return (
      <div>
        <p>Veuillez vous connecter pour accéder à l’aide.</p>
        <a href="https://docs.example.com">Se connecter</a>
      </div>
    );
  }

  return (
    <GitBookProvider siteURL="https://docs.example.com">
      <YourAppContent />
      <GitBookFrame visitor={{ token: token }} />
    </GitBookProvider>
  );
}
```

{% endtab %}
{% endtabs %}

## Pièges courants

* **Utiliser un jeton de fournisseur d’identité** – N’utilisez pas un jeton d’accès OIDC ni un jeton ID en tant que `visitor.token`. Utilisez le jeton visiteur HS256 émis par GitBook après l’authentification sur le site de documentation.
* **Chargement de l’intégration avant la connexion** – Envoyez les visiteurs pour la première fois sur le site de documentation afin qu’ils terminent la connexion avant de charger le script ou les composants.
* **Le jeton ne persiste pas entre les domaines** – Les cookies ne persistent pas entre différents domaines en raison des politiques de sécurité du navigateur. Votre application et la documentation doivent être sur le même domaine ou sous-domaine, ou bien vous devez transmettre le jeton directement.
* **Jeton expiré** – Les jetons peuvent expirer. Si l’intégration renvoie des erreurs d’authentification, invitez les utilisateurs à se reconnecter.
* **Utilisation du mauvais nom de cookie** – Le jeton est stocké sous `gitbook-visitor-token`, et non `gitbook-token` ou d’autres variantes.
* **Ne pas transmettre le jeton à init/getFrameURL** – Lorsque vous utilisez l’approche basée sur les cookies, veillez à transmettre le jeton à `GitBook('init', ..., { visitor: { token } })` ou `getFrameURL({ visitor: { token } })`.

## Débogage

Pour vérifier que le jeton est présent, ouvrez la console de votre navigateur et exécutez :

```javascript
document.cookie.split(";").find((c) => c.includes("gitbook-visitor-token"));
```

Si cela renvoie `undefined`, l’utilisateur ne s’est pas encore connecté à votre documentation.

## Étapes suivantes

* [Personnaliser l'intégration](/docs/documentation/fr/publier/embedding/configuration/customizing-docs-embed.md) – Ajouter des messages d’accueil et des actions
* [Créer des outils personnalisés](/docs/documentation/fr/publier/embedding/configuration/creating-custom-tools.md) – Intégrer vos API produit
* [Documentation Docs Embed](/docs/documentation/fr/publier/embedding.md) – Guide d’intégration complet


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/fr/publier/embedding/using-with-authenticated-docs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.