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

Collection users

Handle permissions and user management for a specific collection.

Control which users 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.

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

Responses
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 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
application/json
all ofoptional
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
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

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

Responses
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

List all collections users 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

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
application/json
all ofoptional
get
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"
        }
      }
    }
  ]
}

Was this helpful?