> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # GitBook > Connect a GitBook organization to Oleria to discover who can reach each collection, space and docs site, how they got that access, and which integrations, share links and invite links expose your documentation. Connect a GitBook organization to Oleria to see who has access to your documentation: organization members and guests, the teams that hold permissions, every collection, space and docs site, and the integrations, share links and invite links that reach your content. Oleria reads this data from the GitBook API with an organization admin's personal access token, so you can see where access is over-provisioned and take action directly from Oleria. Each integration covers one GitBook organization. To bring in several organizations, add one integration for each. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your GitBook organization: * **Accounts** - every organization member, with their name, email address, the date they joined, and when they were last seen. Members whose membership GitBook has disabled appear as disabled. Guests - members with no organization role, who see only content shared with them - are marked as external users. * **Account roles** - each member's organization role: **Admin**, **Creator**, **Reviewer**, **Editor**, **Commenter**, **Reader**, or **Guest**. Admins are marked as admins. * **Sign-in** - whether each member can sign in with SAML single sign-on, and whether your organization requires it. GitBook has no two-factor authentication of its own, so members who sign in without SSO show multi-factor authentication as not required, and members who must sign in through your identity provider show it as unavailable, because the identity provider enforces it. * **User groups** - every team, with its members. Team owners appear as the team's owners. * **Resources** - your organization, every collection, space and docs site, and which collection each space or sub-collection belongs to. Deleted spaces appear as deleted, with no access. * **Access** - who can reach each collection, space and site, and with which role: * Members and teams given a role directly on a collection, space or site. When a member is set to **No access** on content, Oleria leaves them out of that content's default access. * The access each organization role gives through the content's default permissions. When content inherits its permissions, Oleria follows the chain up through parent collections to the organization, where each member gets their own organization role. When content sets a specific role for everyone, every member except admins and guests gets that role. When content allows no access, only admins and the members and teams added to it can reach it. * Admins' access to all content, shown through the **Organization Admin** role's admin access to every collection, space and site. * Anonymous read access to published public and unlisted sites and to public and unlisted spaces. When any content is open to the internet, Oleria adds an account named **Anyone on the internet** with read access to it. * **Non-human identities (NHIs)** - three kinds: * **Integrations** installed on your organization, such as Slack or GitHub Sync, with the spaces and sites each one can reach and the permissions (scopes) the integration requests. A paused or pending installation appears as disabled, with no access. * **Private share links** of each site. An active link reaches its site while the site is published to share-link visitors. Each link also appears as a credential. Oleria never reads the link's URL, which contains its secret, and identifies each link by a fingerprint instead of its ID, because the ID is the secret part of the URL. * **Organization invite links**, with the role anyone who uses the link joins with. Each link also appears as a credential. When your organization turns invite links off, every invite link appears as disabled. * **Credentials** - besides share links and invite links, the signing certificate of each SAML provider, with its expiry date, and the signing key of each site that admits visitors through your own authentication. Oleria never reads the signing key itself. * **Activity** - your organization's audit log: changes to members, roles, teams, permissions, content and settings, with who made them. The audit log requires the GitBook Enterprise plan. See [Known limitations](#known-limitations). Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). When a member, grant or link is removed in GitBook, it disappears from Oleria on the next sync. ## Prerequisites * A GitBook organization. The audit log, SAML single sign-on and team owners need the Enterprise plan; everything else works on any plan with members. * A GitBook user with the **Admin** role in that organization, to own the personal access token. GitBook shows invite links and the audit log only to admins, and only admins can make the changes the remediation actions make. Oleria acts with this user's permissions and refuses a token whose user isn't an admin. * Admin access to the Oleria workspace. > [!WARNING] > > Create the token as a dedicated GitBook admin user instead of a named person's account. If that user leaves the organization or loses the **Admin** role, syncs and actions stop working. ## Create a GitBook personal access token GitBook's API authenticates with personal access tokens. A token has the same access as the user who creates it, and no scopes or expiry date. **1. Sign in as the organization admin** Sign in to [app.gitbook.com](https://app.gitbook.com) as the admin who will own the token. **2. Open developer settings** Open your account settings, then select **Developer settings**. **3. Create the token** Create a new token. Give it a name (for example, `Oleria`), then copy the token. > [!NOTE] > > GitBook shows the token value only once, when you create it. Copy it now and store it securely. **4. Find your organization ID (optional)** Open your organization in GitBook and copy the ID from the URL: it's the part after `/o/` in `app.gitbook.com/o//`. You can skip this if the token's user is an admin of only one organization. > [!NOTE] > > The exact location of these settings can change over time. If the steps above don't match what you see, refer to GitBook's own documentation. ## Connect GitBook to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations** -> select **GitBook**. **2. Complete the connection form** Fill in the connection form: | Field | Notes | | :- | :- | | API token | Required. The personal access token you created. Oleria stores it encrypted. | | Organization ID | Optional. The ID of the organization to connect. Leave it blank to connect the only organization the token's user administers. You can't change it after you connect. | **3. Confirm the connection** Select **Authenticate**. Before it saves anything, Oleria checks that: * GitBook accepts the token. * The organization exists and the token's user is a member of it. If you left **Organization ID** blank, Oleria connects the organization the token's user administers, and asks for the ID if they administer none or several. * The token's user has the **Admin** role in the organization. If a check fails, Oleria shows which one and how to fix it. Find the newly connected organization on the **Connected** tab of your Oleria **Integrations** page. ## Verify the integration Confirm the GitBook organization appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, check that members, teams, collections, spaces, sites, integrations and links appear in your Oleria workspace. > [!NOTE] > > When you edit the integration, leave **API token** blank to keep the stored token. A new token must belong to an admin of the same organization. If the token is revoked or its user loses the **Admin** role, syncs fail until you update the integration. ## Remediation actions Oleria can take these actions in GitBook. Each one runs with the permissions of the user who owns the token, who must be an organization **Admin**. Before it offers an action, Oleria checks that the token works and that its user is an admin. | Action | What it does | Revert | | :- | :- | :- | | Add user to group | Adds an organization member to a team, as a member. | Supported - removes the user from the team again. | | Remove user from group | Removes a user from a team. | Supported - adds the user back with the team role they had (owner or member). | | Add user to role | Gives a member an organization role. A member holds one organization role, so this replaces their current role - but only with a higher one. If the member already has the role or a higher one, the action changes nothing. | Supported - restores the member's previous role. | | Remove user from role | Removes a member's organization role, which makes them a guest: they keep only the content they were added to directly or through a team. | Supported - restores the role. | | Delete user | Removes the member from the GitBook organization. | Not supported - re-invite the member in GitBook and add back their teams and content roles. | | Revoke permission to a resource | Removes a user's direct role on a collection, space or site. Access through a team or an organization role is unchanged, and the result says which access remains. | Supported - gives the user the same role again. | | Revoke anonymous access | Unpublishes a public, unlisted or share-link site, which takes it offline for every visitor. Its content and settings are kept. | Supported - publishes the site again. | | Disable NHI | For a share link, deactivates the link. For an invite link, deletes the link. For an integration, uninstalls it from the organization. | Supported for share links (reactivates the link). Not supported for invite links (create a new link instead) or integrations (reinstall the integration and configure it again). | | Create user | Invites an email address to the organization without choosing a role, so GitBook adds them as a **Guest**; use **Add user to role** to give them an organization role. It also adds the new member to the teams you choose. If the email already belongs to a member, Oleria doesn't invite them again, but still adds them to the teams you choose. | Supported when GitBook added the user right away - removes them from the organization. For an existing member, removes only the team memberships the action added. Not supported while the invitation is pending - revoke it in GitBook. | | Create group | Creates a team. The action fails if a team with the same name already exists. | Supported while the team has no members - deletes the team. | | Remove access for external accounts | For a guest, removes every role they were given directly on a collection, space or site. | Supported - gives the guest the same roles again. | | Revoke access to an externally shared asset | For a collection, space or site, removes every guest's direct role on it. For a site, also deactivates its active share links. | Supported - gives the guests their roles again and reactivates the links the action deactivated. | Keep these limits in mind when you use these actions: * **No disable or enable.** GitBook's API can't disable a member, so **Delete user** is the only way to remove a member's access from Oleria, and it can't be reverted. * **Revoke permission removes only a direct role.** If the user reaches the content through a team or their organization role, there's no direct role to remove, so the action makes no change and its result lists the remaining access. To remove that access, remove the user from the team or change their organization role. * **Revoke anonymous access works only on sites.** GitBook's API can't change a space's visibility, so the action fails for a space. If the site is unpublished, or admits only visitors your own authentication signs in, the action makes no change. * **Reverting may need a plan upgrade.** If GitBook requires a plan upgrade before a site can be published again, reverting **Revoke anonymous access** fails and the site stays offline. * **Reverting doesn't undo later changes.** If someone changed the member's role, team membership, the content role or the share link after the action ran, reverting leaves it as it is and says so. * **A lost reply doesn't fail a change that was made.** If GitBook makes a change but its reply is lost, Oleria reads the member, team, content, site or link again. If the change shows, the action succeeds. * **Oleria won't change the token owner's own access**, because the integration would lose access to the organization. This covers adding them to or removing them from a team, removing them from the organization, removing their role, and changing their content roles. * **Disable NHI fails if the target is gone.** If the share link, invite link or integration no longer exists, the action fails instead of reporting success. * **Pending invitations can't be reverted.** When GitBook doesn't add an invited user right away, the invitation waits until they accept, and GitBook's API can't cancel it. Revoke it in GitBook instead. * **External means guests.** **Remove access for external accounts** works only on guests, members with no organization role, and fails for other members. Team memberships are kept, and the result lists them. **Revoke access to an externally shared asset** leaves members' roles as they are and keeps the site published; use **Revoke anonymous access** to take it offline. * **External actions undo themselves on failure.** If GitBook refuses a change part way through, Oleria gives back the roles it already removed and reports the failure. ## Known limitations * **Audit log requires Enterprise.** GitBook offers its audit log only on the Enterprise plan. On other plans, Oleria collects no activity and the rest of the sync is unaffected. The audit log isn't yet verified against a live Enterprise organization, so activity types may be refined once GitBook's action names are confirmed. * **No two-factor or password data.** GitBook accounts have no password and GitBook has no two-factor authentication of its own, so there's no last-password-change date or two-factor status. Which sign-in method a member uses (email link, Google or GitHub) isn't available either, except SAML single sign-on. * **Personal access tokens aren't discovered.** GitBook has no API that lists users' personal access tokens, including the one this integration uses. * **Pending invitations aren't shown.** Users invited by email appear only after they accept. * **Site permissions don't flow into spaces.** In GitBook, a site's permissions can override the defaults of the spaces it publishes. Oleria shows a site's permissions on the site, and each space's own permissions and defaults on the space. * **A direct role lower than the default shows both.** In GitBook, a role given directly on content overrides the member's default access there. If that direct role is lower than the default (for example, Reader on a space where their default would be Editor), Oleria shows both, so reviews see the higher one. A direct **No access** is honoured. * **SAML providers and team owners require Enterprise.** On other plans, SAML certificates and team owners aren't shown. * **No owners for content or integrations.** GitBook doesn't record who created a space, collection, site, integration installation or link. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.