The 2026 State of Docs survey is live 📝 Whether you write, edit, or just rely on docs, we want to hear from you!
Take the survey
PricingLog inSign up

Collection permissions

Manage which members and teams can access or contribute to a collection of spaces.

Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.

Invite to a collection

post
Authorizations
Path parameters
collectionIdstringRequired

The unique id of the collection

Body
roleone ofRequired

Role to set.

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
OK
post
POST /v1/collections/{collectionId}/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

List an org team's permission in 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
200
Listing of teams who have been added to a collection.
application/json
Responseall of
get
GET /v1/collections/{collectionId}/permissions/teams HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Listing of teams who have been added to a collection.

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "permission": "admin",
      "team": {
        "object": "team",
        "id": "text",
        "title": "text",
        "members": 1,
        "spaces": 1,
        "createdAt": "2026-02-18T11:55:12.893Z",
        "permissions": {
          "admin": true,
          "view": true
        }
      }
    }
  ]
}

Remove an org team from a collection

delete
Authorizations
Path parameters
collectionIdstringRequired

The unique id of the collection

teamIdstringRequired

The unique ID of the Team

Responses
204
The team was not found in the collection
delete
DELETE /v1/collections/{collectionId}/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 collection

patch
Authorizations
Path parameters
collectionIdstringRequired

The unique id of the collection

teamIdstringRequired

The unique ID of the Team

Body
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
patch
PATCH /v1/collections/{collectionId}/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 collection user permissions

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
200
Listing of users who have been added to a collection.
application/json
Responseall of
get
GET /v1/collections/{collectionId}/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 user from a collection

delete
Authorizations
Path parameters
collectionIdstringRequired

The unique id of the collection

userIdstringRequired

The unique ID of the User

Responses
204
The user was not found in the collection
delete
DELETE /v1/collections/{collectionId}/permissions/users/{userId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a collection user permission

patch
Authorizations
Path parameters
collectionIdstringRequired

The unique id of the collection

userIdstringRequired

The unique ID of the User

Body
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
patch
PATCH /v1/collections/{collectionId}/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

Last updated

Was this helpful?