Space permissions

Manage which members and teams roles and permissions on a per-space basis.

Give your collaborators the right level of access for specific spaces, or assign entire teams to your spaces and streamline the process of granting or revoking access at scale, without dealing with individual user roles.

Invite a user or a team to a space

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

Body

application/json

or

Responses

204

OK

404

No team or user with the provided Id

application/json

post

/spaces/{spaceId}/permissions

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/permissions HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "role": "admin",
  "teams": [
    "text"
  ]
}

No content

Remove an org team from a space

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

teamIdstringRequired

The unique ID of the Team

Responses

204

The team was not found in the space

205

The team has been removed from the space

400

Team does not have access to space

application/json

delete

/spaces/{spaceId}/permissions/teams/{teamId}

HTTPcURLJavaScriptPython

DELETE /v1/spaces/{spaceId}/permissions/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update an org team's permission in a space

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

teamIdstringRequired

The unique ID of the Team

Body

application/json

roleone ofOptional

The role of a member in an organization, null for guests

string · enum · nullableOptional

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

Possible values:

Responses

204

Team permission was updated

404

No team found with the given ID

application/json

patch

/spaces/{spaceId}/permissions/teams/{teamId}

HTTPcURLJavaScriptPython

PATCH /v1/spaces/{spaceId}/permissions/teams/{teamId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "admin"
}

No content

List space user permissions

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

200

Listing of users who have been added to a space.

application/json

404

No space was found with the given Id

application/json

get

/spaces/{spaceId}/permissions/users

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/permissions/users HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Remove a space user

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

userIdstringRequired

The unique ID of the User

Responses

204

The user was not found in the space

205

The user has been removed from the space

delete

/spaces/{spaceId}/permissions/users/{userId}

HTTPcURLJavaScriptPython

DELETE /v1/spaces/{spaceId}/permissions/users/{userId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update space user permissions

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

The unique id of the space

userIdstringRequired

The unique ID of the User

Body

application/json

roleone ofOptional

The role of a member in an organization, null for guests

string · enum · nullableOptional

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

Possible values:

Responses

204

User permission was updated

404

No user found with the given ID

application/json

patch

/spaces/{spaceId}/permissions/users/{userId}

HTTPcURLJavaScriptPython

PATCH /v1/spaces/{spaceId}/permissions/users/{userId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "admin"
}

No content

List an org team's permission in a space

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

200

Listing of teams who have been added to a space.

application/json

404

No space was found with the given Id

application/json

get

/spaces/{spaceId}/permissions/teams

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/permissions/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2026-02-16T19:58:01.532Z",
        "permissions": {
          "admin": true,
          "view": true
        }
      }
    }
  ]
}

List all space users permissions

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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.

Possible values:

Responses

200

Listing of users who can access the space.

application/json

get

/spaces/{spaceId}/permissions/aggregate

HTTPcURLJavaScriptPython

GET /v1/spaces/{spaceId}/permissions/aggregate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Listing of users who can access the space.

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

List all collections users permissions

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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.

Possible values:

Responses

200

Listing of users who can access the collections.

application/json

get

/collections/{collectionId}/permissions/aggregate

HTTPcURLJavaScriptPython

GET /v1/collections/{collectionId}/permissions/aggregate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Listing of users who can access the collections.

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