The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

Permissions

Configure and manage access control and user permissions.

List permissions for users in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who have been added to a space.

List permissions for teams in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-04-03T19:42:46.828Z"
      }
    }
  ]
}

Listing of teams who have been added to a space.

List permissions for all users in a space.

get
Authorizations
Path parameters
spaceIdstringrequired

The unique id of the space

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

rolestring · enumoptional

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who can access the space.

List permissions for teams in a collection.

get
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-04-03T19:42:46.828Z"
      }
    }
  ]
}

Listing of teams who have been added to a collection.

List permissions for users in a collection.

get
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who have been added to a collection.

List permissions for all users in a collection.

get
Authorizations
Path parameters
collectionIdstringrequired

The unique id of the collection

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

rolestring · enumoptional

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who can access the collections.

List permissions accross all spaces for a member of an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

orderstring · enum · default: "desc"optional

An order for the items in the list

Available options:
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/members/{userId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T19:42:46.828Z",
        "updatedAt": "2025-04-03T19:42:46.828Z",
        "deletedAt": "2025-04-03T19:42:46.828Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-03T19:42:46.828Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      }
    }
  ]
}

Listing of spaces that can be accessed by the user in the organization.

List permissions for all users of a site.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      },
      "origin": {
        "type": "space",
        "space": "text"
      }
    }
  ]
}

Listing of users who can access the site.

Was this helpful?