Delegate access and calendar sharing with Microsoft Graph

Microsoft Graph can read and manage shared or delegated Outlook calendars. Use the Microsoft Graph v1.0 endpoints for new integrations.

A calendar owner can share a calendar with another user and assign a permission role. A delegate can manage meetings in the owner's primary calendar. Sharing and delegation must be established before an application accesses the calendar. The owner sends an invitation, and the recipient accepts it or explicitly adds the calendar in Outlook.

Before you begin

  • Register the application in Microsoft Entra ID.
  • Choose delegated or application access according to the application's sign-in model.
  • Grant only the Microsoft Graph permissions required by the operation.
  • Confirm that the calendar owner has shared or delegated the calendar to the user when the application uses delegated access.
  • Use the calendar owner's user ID or user principal name and the correct calendar ID.

The least-privileged permission depends on the endpoint and operation. For example:

Operation Least-privileged Microsoft Graph permission
List a user's calendars Calendars.ReadBasic
List calendar permissions Calendars.ReadBasic
Create, update, or delete a calendar permission Calendars.ReadWrite
Create an event Calendars.ReadWrite
Read a calendar view Calendars.ReadBasic

Check the permissions table in the documentation for each endpoint. Requirements can differ for user and group calendars and between delegated and application access.

Calendar permission roles

Microsoft Graph represents each share recipient or delegate with a calendarPermission resource. Supported roles include:

Role Access
none No access
freeBusyRead View free/busy status
limitedRead View free/busy status, titles, and locations
read View event details except private-event details
write View and edit non-private events
delegateWithoutPrivateEventAccess Delegate write access without private-event details
delegateWithPrivateEventAccess Delegate write access including private-event details
custom Custom calendar permissions

Only the calendar owner can list, create, update, or delete calendar permissions on behalf of the owner. Listing permissions on behalf of a recipient or delegate returns an empty collection.

Manage calendar permissions

List permissions

GET https://graph.microsoft.com/v1.0/users/{userId}/calendar/calendarPermissions

Create a permission

The following request shares the signed-in user's primary calendar with read access:

POST https://graph.microsoft.com/v1.0/me/calendar/calendarPermissions
Content-Type: application/json

{
  "emailAddress": {
    "name": "Delegate Name",
    "address": "delegate@contoso.com"
  },
  "role": "read"
}

Update a permission

Only the role property can be updated. To change another property, delete the permission and create a new one.

PATCH https://graph.microsoft.com/v1.0/users/{userId}/calendar/calendarPermissions/{permissionId}
Content-Type: application/json

{
  "role": "write"
}

Delete a permission

DELETE https://graph.microsoft.com/v1.0/users/{userId}/calendar/calendarPermissions/{permissionId}

Access calendars and events

List calendars

List the calendars available through the requested user's calendar collection:

GET https://graph.microsoft.com/v1.0/users/{userId}/calendars

For the signed-in user, use:

GET https://graph.microsoft.com/v1.0/me/calendars

Read a calendar view

Use calendarView to return event instances in a specified time range. Include ISO 8601 offsets; if an offset is omitted, Microsoft Graph interprets the value as UTC.

GET https://graph.microsoft.com/v1.0/users/{ownerId}/calendar/calendarView?startDateTime=2026-05-01T00:00:00Z&endDateTime=2026-05-31T23:59:59Z&$select=subject,start,end,organizer

Create an event

An application with the required permission can create an event in the specified user's primary calendar:

POST https://graph.microsoft.com/v1.0/users/{ownerId}/calendar/events
Content-Type: application/json

{
  "subject": "Team meeting",
  "start": {
    "dateTime": "2026-05-01T10:00:00",
    "timeZone": "Pacific Standard Time"
  },
  "end": {
    "dateTime": "2026-05-01T11:00:00",
    "timeZone": "Pacific Standard Time"
  },
  "attendees": [
    {
      "emailAddress": {
        "address": "attendee@contoso.com",
        "name": "Attendee Name"
      },
      "type": "required"
    }
  ]
}

Troubleshoot common responses

401 Unauthorized or InvalidAuthenticationToken

  1. Acquire a new access token.
  2. Confirm that the token audience is Microsoft Graph.
  3. Confirm that the token contains the required delegated scopes or application roles.
  4. Verify the application's Microsoft Entra consent configuration.

403 Forbidden

  1. Compare the granted Microsoft Graph permissions with the endpoint's permissions table.
  2. For delegated access, confirm that the signed-in user has access to the owner's calendar.
  3. Confirm that the request uses the intended delegated or application access model.
  4. If the operation manages calendar permissions, confirm that it is performed on behalf of the calendar owner.

404 Not Found

  1. Verify the user ID or user principal name.
  2. List the user's calendars and use the returned calendar ID.
  3. Confirm that the shared calendar was accepted or explicitly added in Outlook.
  4. Confirm that the calendar or event has not been deleted.

429 Too Many Requests

Wait for the number of seconds specified by the Retry-After response header, and then retry the request. If the response does not include Retry-After, use exponential backoff. Avoid continuous polling and unnecessary collection scans.

Implementation guidance

  • Request only the permissions needed by the application.
  • Use $select to request only required properties when the endpoint supports it.
  • Follow the URL in @odata.nextLink until it is no longer returned when reading a paged collection.
  • Treat access tokens and request headers as sensitive data. Remove tokens and personal data before sharing diagnostic output.
  • Use Microsoft Graph Explorer to test requests with a tenant administrator-approved account and permissions.

Microsoft documentation

  • Last updated on