# Collection permissions

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

## POST /collections/{collectionId}/permissions

> Invite to a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"InviteUsersAndTeams":{"type":"object","properties":{"role":{"description":"Role to set.","$ref":"#/components/schemas/MemberRoleOrGuest"}},"anyOf":[{"type":"object","properties":{"teams":{"type":"array","minItems":1,"items":{"type":"string","description":"The ID of the team to be invited"}}},"required":["teams"]},{"type":"object","properties":{"users":{"type":"array","minItems":1,"items":{"type":"string","description":"The ID of the user to be invited"}}},"required":["users"]}],"required":["role"]},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions":{"post":{"operationId":"inviteToCollection","summary":"Invite to a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"}],"responses":{"204":{"description":"OK"},"404":{"description":"No team or user with the provided Id","$ref":"#/components/responses/NotFoundError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUsersAndTeams"}}}}}}}}
```

## GET /collections/{collectionId}/permissions/teams

> List an org team's permission in collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"OrganizationTeam":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"team\"","enum":["team"]},"id":{"type":"string","description":"Unique identifier for the team."},"title":{"$ref":"#/components/schemas/OrganizationTeamTitle"},"members":{"type":"integer","description":"Count of members in this team."},"spaces":{"type":"number","description":"Count of spaces this team has access to."},"createdAt":{"description":"Date at which the team was created.","$ref":"#/components/schemas/Timestamp"},"permissions":{"type":"object","description":"The set of permissions for the team","properties":{"admin":{"type":"boolean","description":"Can the user manage the team"},"view":{"type":"boolean","description":"Can the user view the team and list its members"}},"required":["admin","view"]}},"required":["object","id","title","members","spaces","createdAt","permissions"]},"OrganizationTeamTitle":{"type":"string","description":"Title of the team","minLength":1,"maxLength":64},"Timestamp":{"type":"string","format":"date-time"}}},"paths":{"/collections/{collectionId}/permissions/teams":{"get":{"operationId":"listTeamPermissionsInCollection","summary":"List an org team's permission in collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"Listing of teams who have been added to a collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","description":"Permission of a team in a content.","properties":{"permission":{"$ref":"#/components/schemas/MemberRole"},"team":{"$ref":"#/components/schemas/OrganizationTeam"}},"required":["permission","team"]}}}}]}}}}}}}}}
```

## DELETE /collections/{collectionId}/permissions/teams/{teamId}

> Remove an org team from a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/collections/{collectionId}/permissions/teams/{teamId}":{"delete":{"operationId":"removeTeamFromCollection","summary":"Remove an org team from a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/teamId"}],"responses":{"204":{"description":"The team was not found in the collection"},"205":{"description":"The team has been removed from the collection"}}}}}}
```

## PATCH /collections/{collectionId}/permissions/teams/{teamId}

> Update an org team's permission in a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"teamId":{"name":"teamId","in":"path","required":true,"description":"The unique ID of the Team","schema":{"$ref":"#/components/schemas/EntityId"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/teams/{teamId}":{"patch":{"operationId":"updateTeamPermissionInCollection","summary":"Update an org team's permission in a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/teamId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/MemberRoleOrGuest"}}}}}},"responses":{"204":{"description":"Team permission was updated"},"404":{"description":"No team found with the given ID","$ref":"#/components/responses/NotFoundError"}}}}}}
```

## GET /collections/{collectionId}/permissions/users

> List collection user permissions

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"listPage":{"name":"page","in":"query","description":"Identifier of the page results to fetch.","schema":{"type":"string"}},"listLimit":{"name":"limit","in":"query","description":"The number of results per page","schema":{"type":"number","minimum":0,"maximum":1000}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"List":{"type":"object","properties":{"next":{"type":"object","properties":{"page":{"type":"string","description":"Unique identifier to query the next results page"}},"required":["page"]},"count":{"type":"number","description":"Total count of objects in the list"}}},"UserContentPermission":{"type":"object","description":"Permission of a user in a content.","properties":{"permission":{"$ref":"#/components/schemas/MemberRole"},"user":{"$ref":"#/components/schemas/User"}},"required":["permission","user"]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]},"User":{"type":"object","properties":{"object":{"type":"string","description":"Type of Object, always equals to \"user\"","enum":["user"]},"id":{"type":"string","description":"Unique identifier for the user"},"displayName":{"type":"string","description":"Full name for the user"},"email":{"type":"string","description":"Email address of the user"},"photoURL":{"type":"string","description":"URL of the user's profile picture"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the user in the API","format":"uri"}},"required":["location"]}},"required":["object","id","displayName","urls"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/users":{"get":{"operationId":"listUserPermissionsInCollection","summary":"List collection user permissions","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/listPage"},{"$ref":"#/components/parameters/listLimit"}],"responses":{"200":{"description":"Listing of users who have been added to a collection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/List"},{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserContentPermission"}}}}]}}}},"404":{"description":"No space found with the given Id","$ref":"#/components/responses/NotFoundError"}}}}}}
```

## DELETE /collections/{collectionId}/permissions/users/{userId}

> Remove a user from a collection

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"}}},"paths":{"/collections/{collectionId}/permissions/users/{userId}":{"delete":{"operationId":"removeUserFromCollection","summary":"Remove a user from a collection","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/userId"}],"responses":{"204":{"description":"The user was not found in the collection"},"205":{"description":"The user has been removed from the collection"}}}}}}
```

## PATCH /collections/{collectionId}/permissions/users/{userId}

> Update a collection user permission

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"collection-permissions","description":"Control which users and teams have access to a collection's spaces. This ensures only the right individuals can view or modify sensitive content.\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"collectionId":{"name":"collectionId","in":"path","required":true,"description":"The unique id of the collection","schema":{"$ref":"#/components/schemas/EntityId"}},"userId":{"name":"userId","in":"path","required":true,"description":"The unique ID of the User","schema":{"type":"string"}}},"schemas":{"EntityId":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","description":"A unique entity identifier"},"MemberRoleOrGuest":{"description":"The role of a member in an organization, null for guests","oneOf":[{"$ref":"#/components/schemas/MemberRole"},{"type":"null"}]},"MemberRole":{"type":"string","description":"\"The role of a member in an organization.\n\"admin\": Can administrate the content: create, delete spaces, ...\n\"create\": Can create content.\n\"review\": Can review content.\n\"edit\": Can edit the content (live or change requests).\n\"comment\": Can access the content and its discussions.\n\"read\": Can access the content, but cannot update it in any way.\n","enum":["admin","create","edit","review","comment","read"]}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/collections/{collectionId}/permissions/users/{userId}":{"patch":{"operationId":"updateUserPermissionInCollection","summary":"Update a collection user permission","tags":["collection-permissions"],"parameters":[{"$ref":"#/components/parameters/collectionId"},{"$ref":"#/components/parameters/userId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/MemberRoleOrGuest"}}}}}},"responses":{"204":{"description":"User permission was updated"},"404":{"description":"No user found with the given ID","$ref":"#/components/responses/NotFoundError"}}}}}}
```