GitBook Site Publishing Auth API

openapi: 3.2.0
info:
  title: GitBook Site Publishing Auth API
  description: The GitBook API
  termsOfService: https://policies.gitbook.com
  contact:
    name: API Support
    url: https://gitbook.com/support
    email: support@gitbook.com
  version: 0.0.1-beta
servers:
- url: '{host}/v1'
  variables:
    host:
      default: https://api.gitbook.com
security:
- user: []
- user-internal: []
- user-staff: []
- integration: []
- integration-installation: []
tags:
- name: site-publishing-auth
  x-page-title: Site auth
  x-page-description: Manage the authentication needed for publishing your site.
  x-parent: sites
  description: 'Configure the credentials or tokens required to publish documentation externally. This helps ensure your site is consistently kept up to date.


    {% openapi-schemas spec="gitbook" schemas="SitePublishingAuth" grouped="false" %}

    The SitePublishingAuth object

    {% endopenapi-schemas %}'
paths:
  /orgs/{organizationId}/sites/{siteId}/publishing/auth:
    get:
      operationId: getSitePublishingAuthById
      summary: Get the published content authentication configuration for a site
      description: Retrieves the authentication settings that protect a site's published content. Use this to review the current auth method before making changes or troubleshooting access issues.
      x-gitbook-mcp: true
      tags:
      - site-publishing-auth
      security:
      - user: []
      - oauth:
        - site:auth:read
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitePublishingAuth'
        '400':
          $ref: '#/components/responses/BadRequestError'
    patch:
      operationId: updateSitePublishingAuthById
      summary: Update the published content authentication configuration for a site
      description: Modifies the authentication method used to protect a site's published content. Use this to enable, disable, or change the auth method for a published site.
      x-gitbook-mcp: true
      tags:
      - site-publishing-auth
      security:
      - user: []
      - oauth:
        - site:auth:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SitePublishingAuthUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitePublishingAuth'
        '400':
          $ref: '#/components/responses/BadRequestError'
  /orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate:
    post:
      operationId: regenerateSitePublishingAuthById
      summary: Regenerate the private key for a site's published content authentication
      description: Re-generates the private key used for the site's publishing authentication (e.g., JWT signing key for SSO). Existing tokens signed with the old key will become invalid immediately. Use this to rotate credentials after a security incident or as part of a regular key rotation policy.
      x-gitbook-mcp:
        destructive: true
      tags:
      - site-publishing-auth
      security:
      - user: []
      - oauth:
        - site:auth:write
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitePublishingAuth'
        '400':
          $ref: '#/components/responses/BadRequestError'
components:
  schemas:
    SitePublishingAuthUpdate:
      allOf:
      - oneOf:
        - $ref: '#/components/schemas/VisitorAuthCustomBackend'
        - $ref: '#/components/schemas/VisitorAuthIntegrationBackend'
      - type: object
        properties:
          fallbackURL:
            type:
            - string
            - 'null'
            format: uri
            description: A fallback URL that will be used if authentication fails. If not provided, the fallback URL will not be changed. If set to null, the fallback URL will be unset.
          logoutURL:
            type:
            - string
            - 'null'
            format: uri
            description: A logout URL used to log visitors out from the upstream custom auth backend. If not provided, the logout URL will not be changed. If set to null, the logout URL will be unset.
    SitePublishingAuth:
      allOf:
      - oneOf:
        - $ref: '#/components/schemas/VisitorAuthCustomBackend'
        - $ref: '#/components/schemas/VisitorAuthIntegrationBackend'
      - type: object
        properties:
          object:
            type: string
            description: Type of Object, always equals to "publishing-auth"
            enum:
            - publishing-auth
          privateKey:
            type: string
            description: Private key used to sign JWT tokens.
          fallbackURL:
            type: string
            format: uri
            description: URL to redirect to when the authenticated access secret is invalid.
          logoutURL:
            type: string
            format: uri
            description: URL used to log visitors out from the upstream custom auth backend.
          integration:
            type: string
            description: 'Name of the authenticated access integration installed on the site (if any).

              It is also the one being used as VA backend when the published auth settings are configured to use "integration" as backend.

              '
        required:
        - object
        - privateKey
    EntityId:
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      description: A unique entity identifier
    VisitorAuthCustomBackend:
      type: object
      title: Custom backend for authenticated access
      properties:
        backend:
          type: string
          description: Custom backend for authenticated access
          enum:
          - custom
      required:
      - backend
    VisitorAuthIntegrationBackend:
      type: object
      title: Integration backend for authenticated access
      properties:
        backend:
          type: string
          description: Integration as backend for authenticated access
          enum:
          - integration
      required:
      - backend
  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    enum:
                    - 400
                  message:
                    type: string
                required:
                - code
                - message
  parameters:
    siteId:
      name: siteId
      in: path
      required: true
      description: The unique id of the site
      schema:
        type: string
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The unique id of the organization
      schema:
        $ref: '#/components/schemas/EntityId'
  securitySchemes:
    user:
      type: http
      scheme: bearer
    user-internal:
      type: http
      scheme: bearer
    user-staff:
      type: http
      scheme: bearer
    integration:
      type: http
      scheme: bearer
    integration-installation:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.gitbook.com/authorize
          tokenUrl: https://oauth.gitbook.com/token
          scopes:
            user:read: Read your GitBook user profile.
            organization:read: Read the organizations you belong to, their settings and metadata, and their AI agent conversations.
            organization:write: Create organizations, and update organization settings and AI agent conversations.
            organization:members:read: Read organization members, teams, invites and link invites.
            organization:members:write: Manage organization members, teams, invites and link invites.
            organization:ask: Ask AI questions across an organization's content.
            organization:search: Search across an organization's content.
            space:read: Read spaces and their content, including pages, change requests and their reviews, comments, files and revision history.
            space:write: Create, update and delete spaces and their content, including change requests (create, edit, review), comments, and content imports and exports. Merging a change request also requires change-request:merge.
            space:permissions:read: Read the users and teams who have access to spaces and collections.
            space:permissions:write: Manage who has access to spaces and collections, including inviting users and teams.
            change-request:merge: Merge change requests, publishing their changes to the space. Creating, editing and reviewing change requests only requires space:write.
            site:read: Read sites and their settings, including navigation structure, linked spaces, customization, redirects, topics, AI configuration and documentation issues.
            site:write: Create, update and delete sites and their settings, including navigation structure (sections, linked spaces, external links), customization, redirects, topics and AI configuration.
            site:publish: Publish and unpublish sites, controlling their public exposure.
            site:permissions:read: Read the users and teams who have access to sites.
            site:permissions:write: Manage who has access to sites, including inviting users and teams.
            site:auth:read: Read how visitors authenticate on a site and its security configuration, including private share links.
            site:auth:write: Manage how visitors authenticate on a site and its security configuration, including private share links.
            site:insights:read: Read site analytics and insights, including the questions visitors asked Ask AI and the answers they received.
            site:ask: Ask AI questions across a site's content.
            site:search: Search across a site's content.
            integration:read: Read integrations, their status and where they are installed.
            integration:installations:read: Read integration installations and their configuration, which can include credentials for third-party services.
            integration:installations:write: Install and configure integrations on an organization, its spaces and its sites.
            integration:publish: Publish integrations, which can request their own permissions on your content, and route their events to a development tunnel.
            integration:delete: Unpublish integrations, permanently deleting them and every installation of them.
            openapi:read: Read OpenAPI specifications.
            openapi:write: Create, update and delete OpenAPI specifications.
x-provenance:
  method: harvested
  publisher: GitBook
  source: https://api.gitbook.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)