> ## Documentation Index
> Fetch the complete documentation index at: https://www.domo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Modify Collection Permissions

> Modify the permissions for a user, group, or app instance on a collection.

## Permission Inheritance
**Users and groups inherit** permissions from the app, so often the most convenient thing is to give the _app_ the permissions you want all people to have. Anyone who gets the app shared with them inherits its permissions on the collection and its documents. By **default**, apps are given the following permissions on their collections: `read`, `create_content`, `read_content`, `update_content`, and `delete_content`.

You can set the app permissions with this API or using the **wiring screen** of an app card.

## Direct Permissions
However, in situations where not everyone should be able to create, update or delete documents, you'll need a more nuanced permission model. You can give individual users and groups permissions using this API or [AppDB Admin](/s/article/9221297758615). 

When you need control down to the document level, you can leverage [Document-level Security](/portal/API-Reference/app-framework-apis/AppDB-API#document-level-security).

<Info>**Adds by default.** This endpoint **adds to** existing permissions, unless you pass `overwrite=true`. Then it will **replace** the entire permission set for that entity with the permissions you specify. To remove all permissions for an entity, use [Delete Permissions](/api-reference/appdb-api/delete-permissions).</Info>

## Available Permissions

| Permission       | Grants |
| ---------------- | ------ |
| `admin`          | All permissions to the collection and its documents |
| `write`          | Update the collection's properties |
| `read`           | Read the collection's properties |
| `share`          | Add or remove permissions this entity already holds |
| `delete`         | Delete the collection |
| `create_content` | Create documents in the collection |
| `update_content` | Update documents in the collection |
| `read_content`   | Read documents in the collection |
| `delete_content` | Delete documents from the collection |

Removing all entity permissions leaves only users with the **Manage AppDB** grant with access.




## OpenAPI

````yaml /openapi/framework/appdb.yaml put /domo/datastores/v1/collections/{collectionName}/permission/{entity}/{entityId}
openapi: 3.0.0
info:
  title: Domo AppDB API
  version: v1
  description: >
    AppDB API for storing arbitrary JSON documents similar to a NoSQL database.
    This enables storing state within your DomoApp

    with optional syncing to Domo DataSets.


    Three layers provide data storage:

    - **Datastores**: Analogous to a database. A CustomApp has a single
    datastore created automatically.

    - **Collections**: Analogous to a collection in NoSQL or table in relational
    databases.

    - **Documents**: Analogous to documents in NoSQL or table rows in relational
    databases.
servers:
  - url: https://{instance}.domo.com
    description: Domo Instance
    variables:
      instance:
        default: example
        description: Your Domo instance name
security: []
paths:
  /domo/datastores/v1/collections/{collectionName}/permission/{entity}/{entityId}:
    put:
      tags:
        - AppDB API
      summary: Modify Collection Permissions
      description: >
        Modify the permissions for a user, group, or app instance on a
        collection.


        ## Permission Inheritance

        **Users and groups inherit** permissions from the app, so often the most
        convenient thing is to give the _app_ the permissions you want all
        people to have. Anyone who gets the app shared with them inherits its
        permissions on the collection and its documents. By **default**, apps
        are given the following permissions on their collections: `read`,
        `create_content`, `read_content`, `update_content`, and
        `delete_content`.


        You can set the app permissions with this API or using the **wiring
        screen** of an app card.


        ## Direct Permissions

        However, in situations where not everyone should be able to create,
        update or delete documents, you'll need a more nuanced permission model.
        You can give individual users and groups permissions using this API or
        [AppDB Admin](/s/article/9221297758615). 


        When you need control down to the document level, you can leverage
        [Document-level
        Security](/portal/API-Reference/app-framework-apis/AppDB-API#document-level-security).


        <Info>**Adds by default.** This endpoint **adds to** existing
        permissions, unless you pass `overwrite=true`. Then it will **replace**
        the entire permission set for that entity with the permissions you
        specify. To remove all permissions for an entity, use [Delete
        Permissions](/api-reference/appdb-api/delete-permissions).</Info>


        ## Available Permissions


        | Permission       | Grants |

        | ---------------- | ------ |

        | `admin`          | All permissions to the collection and its documents
        |

        | `write`          | Update the collection's properties |

        | `read`           | Read the collection's properties |

        | `share`          | Add or remove permissions this entity already holds
        |

        | `delete`         | Delete the collection |

        | `create_content` | Create documents in the collection |

        | `update_content` | Update documents in the collection |

        | `read_content`   | Read documents in the collection |

        | `delete_content` | Delete documents from the collection |


        Removing all entity permissions leaves only users with the **Manage
        AppDB** grant with access.
      parameters:
        - $ref: '#/components/parameters/CollectionName'
        - $ref: '#/components/parameters/EntityType'
        - $ref: '#/components/parameters/EntityId'
        - name: permissions
          in: query
          required: true
          description: One or more permissions to apply. Pass as a comma-separated list.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - admin
                - write
                - read
                - share
                - delete
                - create_content
                - update_content
                - read_content
                - delete_content
          example: read,create_content,update_content,read_content
        - name: overwrite
          in: query
          required: false
          description: >
            Controls how the specified permissions are applied to the entity's
            existing permission set.


            - `false` (default) — **additive**: merges the specified permissions
            with any permissions the entity already holds.

            - `true` — **replace**: discards the entity's existing permissions
            and replaces them with exactly the permissions you specify.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Permissions updated successfully. No response body is returned.
        '400':
          description: >-
            The request could not be validated — for example, the `entityId`
            does not resolve to an existing entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 400
                statusReason: >-
                  status 400 reading
                  CollectionsResourceClient#setCollectionPermissions(UUID,String,String,Set,Boolean);
                  content:

                  {"message":"Unable to verify user with id
                  1","status":400,"statusReason":"Bad
                  Request","toe":"4TZK5F0MHP-VLK9M-YVHFY"}
                toe: 4TZK5F0MHP-VLK9M-YVHFY
        '403':
          description: You do not have the SHARE permission on this collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 403
                statusReason: >-
                  status 403 reading
                  CollectionsResourceClient#setCollectionPermissions(UUID,String,String,Set,Boolean);
                  content:

                  {"message":"The item you're looking for can not be
                  found","status":403,"statusReason":"Forbidden","toe":"6CPYAXAZXA-8DYRE-V4TQC"}
                toe: 6CPYAXAZXA-8DYRE-V4TQC
        '404':
          description: >-
            Collection not found. Verify the collection name is correct (it is
            case-sensitive) and that the collection has been created or
            correctly wired in this app's datastore.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: 404
                statusReason: >-
                  DA0088: Collection 'T' was not found in datastore
                  fcd8baba-9524-4fb5-b94b-b3d3b588e740 - it may not exist on
                  this instance or may not be accessible
                toe: DSKD0CWR0C-NTWA3-UNZVI
      x-codeSamples:
        - lang: JavaScript
          label: domo.js
          source: >-
            const collectionName = 'YourCollection';


            // Add permissions to a user's existing set (additive, default
            behavior)

            const userId = '540824222';

            domo.put(
              `/domo/datastores/v1/collections/${collectionName}/permission/USER/${userId}?permissions=read,create_content,read_content,update_content,delete_content`
            ).then(() => console.log('user permissions updated'));


            // Replace the app instance's permission set entirely
            (overwrite=true)

            // The instance UUID is the subdomain of the app's origin URL.

            const instanceId = window.location.hostname.split('.')[0];

            domo.put(
              `/domo/datastores/v1/collections/${collectionName}/permission/RYUU_APP/${instanceId}?permissions=read,read_content&overwrite=true`
            ).then(() => console.log('app permissions replaced'));
        - lang: cURL
          label: cURL
          source: |-
            # This API is only available inside a Domo app.
            # Use the JavaScript (domo.js) tab for the correct usage.
        - lang: Python
          label: Python
          source: |-
            # This API is only available inside a Domo app.
            # Use the JavaScript (domo.js) tab for the correct usage.
        - lang: PHP
          label: PHP
          source: |-
            // This API is only available inside a Domo app.
            // Use the JavaScript (domo.js) tab for the correct usage.
        - lang: Go
          label: Go
          source: |-
            // This API is only available inside a Domo app.
            // Use the JavaScript (domo.js) tab for the correct usage.
        - lang: Java
          label: Java
          source: |-
            // This API is only available inside a Domo app.
            // Use the JavaScript (domo.js) tab for the correct usage.
        - lang: Ruby
          label: Ruby
          source: |-
            # This API is only available inside a Domo app.
            # Use the JavaScript (domo.js) tab for the correct usage.
components:
  parameters:
    CollectionName:
      name: collectionName
      in: path
      required: true
      description: The name given to the collection in the manifest. Case-sensitive.
      schema:
        type: string
    EntityType:
      name: entity
      in: path
      required: true
      description: The type of entity the permissions apply to.
      schema:
        type: string
        enum:
          - USER
          - GROUP
          - RYUU_APP
    EntityId:
      name: entityId
      in: path
      required: true
      description: >-
        The ID of the entity the permissions apply to. For a **USER** or
        **GROUP**, this is the numeric ID (for example, `870010733`). For a
        **RYUU_APP**, this is the app instance's UUID — the same value as the
        app's datastore UUID, which also appears as the subdomain of the app's
        origin (e.g., `https://<instance-uuid>.domoapps.domo.com`).
      schema:
        type: string
      examples:
        userOrGroup:
          summary: User or group (numeric ID)
          value: '870010733'
        app:
          summary: App instance (UUID)
          value: fcd8baba-9524-4fb5-b94b-b3d3b588e740
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: >-
            A plain-English explanation of the error. Present on some errors but
            not all.
        status:
          type: integer
          description: The HTTP error code
        statusReason:
          type: string
          description: >-
            A human-readable error message, sometimes including nested error
            detail
        toe:
          type: string
          description: >-
            Thread of Execution; a unique identifier that Support can use to
            find more info about your problem
      example:
        status: 404
        statusReason: 'DA0088: Invalid collection name: Students'
        toe: FTYRJMBLKD-5HB2Z-H6W8A

````