Permissions

Configure and manage access control and user permissions.

Was this helpful?

List permissions for users in a space.

get

/spaces/{spaceId}/permissions/users

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who have been added to a space.

List permissions for all users in a space.

get

/spaces/{spaceId}/permissions/aggregate

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

rolestring · enum

"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.

Options: admin, create, edit, review, comment, read

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who can access the space.

List permissions for users in a collection.

get

/collections/{collectionId}/permissions/users

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ]
}

Listing of users who have been added to a collection.

List permissions for all users in a collection.

get

/collections/{collectionId}/permissions/aggregate

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

rolestring · enum

Options: admin, create, edit, review, comment, read

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "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

/orgs/{organizationId}/members/{userId}/spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

userIdstringrequired

The unique ID of the User

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

orderstring · enum · default: desc

An order for the items in the list

Options: asc, desc

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/members/{userId}/spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "space": {
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-03-09T02:39:24.852Z",
        "updatedAt": "2025-03-09T02:39:24.852Z",
        "deletedAt": "2025-03-09T02:39:24.852Z",
        "editMode": "live",
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-03-09T02:39:24.852Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "object": "space",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "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

/orgs/{organizationId}/sites/{siteId}/permissions/aggregate

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/permissions/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "user": {
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "object": "user",
        "urls": {
          "location": "https://example.com"
        }
      },
      "origin": {
        "space": "text",
        "type": "space"
      }
    }
  ]
}

Listing of users who can access the site.

List permissions for teams in a space.

get

/spaces/{spaceId}/permissions/teams

Authorizations

Path parameters

spaceIdstringrequired

The unique id of the space

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/spaces/{spaceId}/permissions/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "team": {
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-03-09T02:39:24.852Z",
        "object": "team"
      }
    }
  ]
}

Listing of teams who have been added to a space.

List permissions for teams in a collection.

get

/collections/{collectionId}/permissions/teams

Authorizations

Path parameters

collectionIdstringrequired

The unique id of the collection

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.gitbook.com/v1/collections/{collectionId}/permissions/teams' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "permission": "admin",
      "team": {
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2025-03-09T02:39:24.852Z",
        "object": "team"
      }
    }
  ]
}

Listing of teams who have been added to a collection.