Brandfolder User Permissions API

openapi: 3.2.0
info:
  title: Brandfolder OpenAPI Reference User Permissions API
  version: v4
  description: 'Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet!

    '
servers:
- url: https://brandfolder.com/api/v4
security:
- APIToken: []
tags:
- name: user_permissions
  x-displayName: User permissions
  description: 'User permissions describe relationships between Organizations, Brandfolders, Collections, Portals or Brandguides and the users that have access to them.


    Learn more about permissioning in our Knowledge Base article on <a href="https://help.smartsheet.com/115002602273-User-Permissions" target="_blank">User Permissions</a>.

    '
paths:
  /organizations/{organization_id}/user_permissions:
    parameters:
    - name: organization_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgkkd-fr5iv4-cocc75
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - in: header
      name: Accept
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4OrganizationsUserPermissionsByOrganizationIdGet
      summary: List user permissions for an organization
      description: 'Lists user permissions for the matching organization.

        '
      tags:
      - user_permissions
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      responses:
        '200':
          description: 'User permissions for the matching organization.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserPermissionToOrganization'
                  included:
                    type: array
                    description: An array listing the organization and its users.
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/User'
                      - $ref: '#/components/schemas/Organization'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /brandfolders/{brandfolder_id}/user_permissions:
    parameters:
    - name: brandfolder_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgiju-21olts-ce9egi
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - in: header
      name: Accept
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4BrandfoldersUserPermissionsByBrandfolderIdGet
      summary: List user permissions for a Brandfolder
      description: 'Lists user permissions for the matching Brandfolder.

        '
      tags:
      - user_permissions
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      responses:
        '200':
          description: 'User permissions for the matching Brandfolder.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserPermissionToBrandfolder'
                  included:
                    type: array
                    description: An array listing the Brandfolder and its users.
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/User'
                      - $ref: '#/components/schemas/Brandfolder'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /collections/{collection_id}/user_permissions:
    parameters:
    - name: collection_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: oqgkkd-fr5iv4-hh142d
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - in: header
      name: Accept
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4CollectionsUserPermissionsByCollectionIdGet
      summary: List user permissions for a collection
      description: 'Lists user permissions for the matching collection.

        '
      tags:
      - user_permissions
      parameters:
      - in: query
        name: page
        description: 'Set this to a positive, non-zero integer representing the page number of

          the results you want.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
      - in: query
        name: per
        description: 'Set this pagination parameter to the maximum number of results you want

          to receive back from your request.

          '
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 3000
          default: 100
      responses:
        '200':
          description: 'User permissions for the matching collection.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserPermissionToCollection'
                  included:
                    type: array
                    description: An array listing the collection and its users.
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/User'
                      - $ref: '#/components/schemas/Collection'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadataResponse'
                required:
                - data
                - meta
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
  /user_permissions/{user_permission_id}:
    parameters:
    - name: user_permission_id
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for the resource instance.
      example: p2f0ou-3geb4w-123456
    - in: header
      name: Content-Type
      required: true
      schema:
        type: string
        enum:
        - application/json
      example: application/json
    - $ref: '#/components/parameters/Authorization'
    get:
      operationId: opIdApiV4UserPermissionsByIdGet
      summary: Fetch a user permission
      description: 'Returns the matching user permission.

        '
      tags:
      - user_permissions
      parameters:
      - in: header
        name: Accept
        required: true
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      responses:
        '200':
          description: 'The matching user permission.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Unique identifier for the resource instance.
                        example: p2f0ou-3geb4w-123456
                      type:
                        type: string
                        description: The type of the resource.
                        enum:
                        - user_permissions
                      attributes:
                        type: object
                        properties:
                          permission_level:
                            type: string
                            description: 'Access level to the object.


                              Learn more about the permission levels you can grant Users in our Knowledge Base article on <a href="https://help.smartsheet.com/115002602273-User-Permissions" target="_blank">User Permissions</a>.

                              '
                            enum:
                            - guest
                            - collaborator
                            - admin
                            - owner
                      relationships:
                        type: object
                        properties:
                          user:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier for the resource instance.
                                example: p0v24p-g7jy9k-123456
                              type:
                                type: string
                                description: The type of the resource.
                                enum:
                                - users
                          permissible:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier for the resource instance.
                                example: oqgiju-21olts-ce9egi
                              type:
                                type: string
                                description: The type of the resource.
                                enum:
                                - organizations
                                - brandfolders
                                - collections
                    required:
                    - id
                    - type
                    - attributes
                    - relationships
                required:
                - data
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
    delete:
      operationId: opIdApiV4UserPermissionsByIdDelete
      summary: Delete a user permission
      description: "Deletes the matching user permission, revoking the user's access to that\nobject. \n"
      tags:
      - user_permissions
      responses:
        '200':
          description: 'Successful response (always an empty object)

            '
          content:
            application/json:
              schema:
                type: object
                properties: {}
        default:
          description: Generic error payload
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    CollectionAttributes:
      title: Collection attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the collection.
          example: My collection
        tagline:
          type: string
          description: The tagline of the collection.
          example: My collection tag line
        slug:
          type: string
          description: The URL-friendly slug of the collection.
          example: my-collection
        public:
          type: boolean
          description: Set to `true` for hassle-free sharing, allowing search engines to index your brand assets. Otherwise, set to `false` to share only with the users you specify.
          example: false
          default: false
        stealth:
          type: boolean
          description: Set to `true` to remove the collection from appearing in web searches.
          example: false
          default: false
        is_workspace:
          type: boolean
          description: Set to `true` if the collection is a Brandfolder workspace.
          example: false
          default: false
    UserPermissionToCollection:
      title: User permission to a collection
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: p2f0ou-3geb4w-123456
        type:
          type: string
          description: The type of the resource.
          enum:
          - user_permissions
        attributes:
          type: object
          properties:
            permission_level:
              type: string
              description: 'Access level to the object.


                Learn more about the permission levels you can grant Users in our Knowledge Base article on <a href="https://help.smartsheet.com/115002602273-User-Permissions" target="_blank">User Permissions</a>.

                '
              enum:
              - guest
              - collaborator
              - admin
              - owner
        relationships:
          type: object
          properties:
            user:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: p0v24p-g7jy9k-123456
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - users
            permissible:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: oqgkkd-fr5iv4-hh142d
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - collections
      required:
      - id
      - type
      - attributes
      - relationships
    PaginationMetadataResponse:
      title: Pagination metadata
      description: Page context information.
      type: object
      properties:
        current_page:
          type: integer
          format: int32
          example: 1
          minimum: 1
          default: 1
        next_page:
          type:
          - object
          - 'null'
          example: null
          default: null
        prev_page:
          type:
          - object
          - 'null'
          example: null
          default: null
        total_pages:
          example: 1
          minimum: 1
          default: 1
        total_count:
          example: 1
          minimum: 0
          default: 0
      required:
      - current_page
      - next_page
      - prev_page
      - total_pages
      - total_count
    BrandfolderAttributes:
      title: Brandfolder attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the brandfolder.
          example: Brandfolder
        privacy:
          type: string
          description: The privacy setting of the brandfolder.
          example: private
        slug:
          type: string
          description: The URL-friendly slug of the brandfolder.
          example: brandfolder
        tagline:
          type: string
          description: The tagline of the brandfolder.
          example: You expected this - Brandfolder's Brandfolder!
          default: ''
      required:
      - name
      - privacy
      - slug
      - tagline
    UserPermissionToOrganization:
      title: User permission to an organization
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: p2f0ou-3geb4w-123456
        type:
          type: string
          description: The type of the resource.
          enum:
          - user_permissions
        attributes:
          type: object
          properties:
            permission_level:
              type: string
              description: 'Access level to the object.


                Learn more about the permission levels you can grant Users in our Knowledge Base article on <a href="https://help.smartsheet.com/115002602273-User-Permissions" target="_blank">User Permissions</a>.

                '
              enum:
              - guest
              - collaborator
              - admin
              - owner
        relationships:
          type: object
          properties:
            user:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: p0v24p-g7jy9k-123456
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - users
            permissible:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: obte6d-45b4mo-123456
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - organizations
      required:
      - id
      - type
      - attributes
      - relationships
    User:
      title: User
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: p0v24p-g7jy9k-123456
        type:
          type: string
          description: The type of the resource.
          enum:
          - users
        attributes:
          $ref: '#/components/schemas/UserAttributes'
      required:
      - id
      - type
      - attributes
    Organization:
      title: Organization
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgkkd-fr5iv4-cocc75
        type:
          type: string
          description: The type of the resource.
          enum:
          - organizations
        attributes:
          $ref: '#/components/schemas/OrganizationAttributes'
      required:
      - id
      - type
      - attributes
    OrganizationAttributes:
      title: Organization attributes
      type: object
      properties:
        name:
          type: string
          description: The name of the brandfolder.
          example: Brandfolder's Organization
        tagline:
          type: string
          description: The tagline of the brandfolder.
          example: An example tagline for the Organization
        slug:
          type: string
          description: The URL-friendly slug of the brandfolder.
          example: brandfolder-organization
    UserAttributes:
      title: User attributes
      type: object
      properties:
        email:
          type: string
          description: The user's email address.
          example: jane.doe@smartsheet.com
        first_name:
          type: string
          description: The user's first name.
          example: Jane
        last_name:
          type: string
          description: The user's last name.
          example: Doe
      required:
      - email
      - first_name
      - last_name
    Collection:
      title: Collection
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgkkd-fr5iv4-hh142d
        type:
          type: string
          description: The type of the resource.
          enum:
          - collections
        attributes:
          $ref: '#/components/schemas/CollectionAttributes'
      required:
      - id
      - type
      - attributes
    Brandfolder:
      title: Brandfolder
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: oqgiju-21olts-ce9egi
        type:
          type: string
          description: The type of the resource.
          enum:
          - brandfolders
        attributes:
          $ref: '#/components/schemas/BrandfolderAttributes'
      required:
      - id
      - type
      - attributes
    UserPermissionToBrandfolder:
      title: User permission to a Brandfolder
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the resource instance.
          example: p2f0ou-3geb4w-123456
        type:
          type: string
          description: The type of the resource.
          enum:
          - user_permissions
        attributes:
          type: object
          properties:
            permission_level:
              type: string
              description: 'Access level to the object.


                Learn more about the permission levels you can grant Users in our Knowledge Base article on <a href="https://help.smartsheet.com/115002602273-User-Permissions" target="_blank">User Permissions</a>.

                '
              enum:
              - guest
              - collaborator
              - admin
              - owner
        relationships:
          type: object
          properties:
            user:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: p0v24p-g7jy9k-123456
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - users
            permissible:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the resource instance.
                  example: oqgiju-21olts-ce9egi
                type:
                  type: string
                  description: The type of the resource.
                  enum:
                  - brandfolders
      required:
      - id
      - type
      - attributes
      - relationships
  parameters:
    Authorization:
      in: header
      name: Authorization
      required: true
      schema:
        type: string
      description: Bearer token for authentication
  securitySchemes:
    APIToken:
      scheme: bearer
      type: http
      description: API Token.