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 User Permissions. ' 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 User Permissions. ' 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 User Permissions. ' 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 User Permissions. ' 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 User Permissions. ' 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.