Microsoft Word Permissions API

openapi: 3.0.3
info:
  title: Microsoft Graph Word Body Permissions API
  description: REST API for interacting with Word documents in Microsoft 365 and OneDrive via the Microsoft Graph unified endpoint. Provides operations for file management, content access, sharing, permissions, versioning, and document metadata for DriveItem resources.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
security:
- oauth2: []
tags:
- name: Permissions
  description: Operations for managing sharing and permissions on drive items
paths:
  /me/drive/items/{item-id}/permissions:
    get:
      operationId: listPermissions
      summary: Microsoft Word List Permissions
      description: List the effective sharing permissions on a driveItem.
      tags:
      - Permissions
      parameters:
      - $ref: '#/components/parameters/itemId'
      responses:
        '200':
          description: Successfully retrieved permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/invite:
    post:
      operationId: addPermissions
      summary: Microsoft Word Add Permissions
      description: Send a sharing invitation for a DriveItem to grant access to specified recipients.
      tags:
      - Permissions
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteRequest'
      responses:
        '200':
          description: Successfully sent invitations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/createLink:
    post:
      operationId: createSharingLink
      summary: Microsoft Word Create Sharing Link
      description: Create a new sharing link for a DriveItem if the specified link type does not already exist.
      tags:
      - Permissions
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkRequest'
      responses:
        '201':
          description: Successfully created a sharing link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    InviteRequest:
      type: object
      description: Request body for sending sharing invitations.
      required:
      - recipients
      - roles
      properties:
        recipients:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                description: Email address of the recipient.
                example: colleague@contoso.com
          description: Recipients to share with.
        roles:
          type: array
          items:
            type: string
          description: Roles to grant (read, write).
          example:
          - write
        requireSignIn:
          type: boolean
          description: Whether recipients must sign in to access the item.
          example: true
        sendInvitation:
          type: boolean
          description: Whether to send an email notification.
          example: true
        message:
          type: string
          description: Message to include in the sharing invitation.
          example: Please review this document.
    Permission:
      type: object
      description: Represents a sharing permission on a drive item.
      properties:
        id:
          type: string
          description: The unique identifier of the permission.
          example: '500123'
        roles:
          type: array
          items:
            type: string
          description: The type of permission (read, write, owner).
          example:
          - write
        link:
          type: object
          properties:
            type:
              type: string
              description: The type of sharing link.
              example: edit
            webUrl:
              type: string
              format: uri
              description: The URL of the sharing link.
              example: https://contoso-my.sharepoint.com/:w:/p/user/abcdef
            scope:
              type: string
              description: The scope of the link (anonymous, organization).
              example: organization
        grantedTo:
          $ref: '#/components/schemas/IdentitySet'
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
              example: itemNotFound
            message:
              type: string
              description: Human-readable error message.
              example: The resource could not be found.
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                  description: Request correlation ID.
                  example: b0c6a5b0-4c0a-4c8e-9b0a-1234567890ab
                date:
                  type: string
                  format: date-time
                  description: Timestamp of the error.
                  example: '2025-03-21T20:01:37Z'
    PermissionCollection:
      type: object
      description: Collection of permissions.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    CreateLinkRequest:
      type: object
      description: Request body for creating a sharing link.
      required:
      - type
      properties:
        type:
          type: string
          description: Type of sharing link to create (view, edit, embed).
          example: edit
        scope:
          type: string
          description: Scope of the link (anonymous, organization).
          example: organization
        expirationDateTime:
          type: string
          format: date-time
          description: Expiration date and time for the link.
          example: '2025-12-31T23:59:59Z'
    IdentitySet:
      type: object
      description: Keyed collection of identity resources.
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the user.
              example: efee1b77-fb3b-4f65-99d6-274c11914d12
            displayName:
              type: string
              description: Display name of the user.
              example: Jane Smith
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or token expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    itemId:
      name: item-id
      in: path
      required: true
      description: The unique identifier of the drive item.
      schema:
        type: string
      example: 01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow with Microsoft Identity Platform.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Files.Read: Read user files
            Files.ReadWrite: Read and write user files
            Files.Read.All: Read all files the user can access
            Files.ReadWrite.All: Read and write all files the user can access