Access shared calendar with the Graph API

Create event in a shared calendar

Imagine that you have a mailbox associated with a meeting room. You can book the meeting room by creating an event and adding the room to the location and to the attendees.

POST https://graph.microsoft.com/v1.0/me/calendar/events

{
    "subject": "Quick meeting with HR manager",
    "body": {
        "contentType": "HTML",
        "content": "Quick meeting"
    },
    "start": {
        "dateTime": "2023-07-26T14:00:00",
        "timeZone": "UTC"
    },
    "end": {
        "dateTime": "2023-07-26T14:30:00",
        "timeZone": "UTC"
    },
    "location": {
        "displayName": "Room_ZL_5.01",
        "locationUri": "Room_ZL_5.01@4wrvkx.onmicrosoft.com",
        "locationType": "conferenceRoom"
    },
    "attendees": [
        {
            "type": "resource",
            "emailAddress": {
                "name": "Room_ZL_5.01",
                "address": "Room_ZL_5.01@4wrvkx.onmicrosoft.com"
            }
        }
    ]
}

It will create an event in the user's calendar and in the meeting room's calendar (with some delay).

Access shared calendar

To retrieve a list of the events in the room's calendar, you can use the following endpoint:

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/events

You will receive the following error response:

Forbidden - 403
{
    "error": {
        "code": "ErrorAccessDenied",
        "message": "Access is denied. Check credentials and try again."
    }
}

The exception is clear, you don't have permission to access the shared calendar. You will receive the same error when trying to read the calendar:

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendar
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendarView?startDateTime=2023-07-26T00:00:00Z&endDateTime=2023-07-27T00:00:00Z

Checking the Graph API permissions reference, the Calendars.Read.Shared permission allows the app to read events in all calendars that the user can access, including delegated and shared calendars.

Add the Calendars.Read.Shared permission and list the room's events again.

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/events

The response is now:

{
    "error": {
        "code": "ErrorItemNotFound",
        "message": "The specified object was not found in the store.",
        "innerError": {
            "date": "2023-07-26T07:03:59",
            "request-id": "507af386-52c5-44ef-9250-91801f7d53c6",
            "client-request-id": "9fa8d997-8eda-c300-b64e-c1b733aeedf2"
        }
    }
}

There are still no events returned, but the error is different than in the previous case.

Exchange Online

To resolve the ErrorItemNotFound error, you need to add mailbox folder permission to allow a delegated access to the calendar.

It can be done either in the Exchange admin center or by the Exchange Online PowerShell module. In both cases, only the tenant admin can connect to Exchange Online.

Set full access to mailbox in Exchange admin center

Login as the admin to the Exchange admin center. Click on Recipients → Resources. You can manage room mailboxes and equipment mailboxes.

Select the room to check the details. In Exchange admin center, you can declare only full access to the room's mailbox.

Click on Delegation tab → Read and manage (Full Access) → Edit → Add members.

Now, the user JoniS@4wrvkx.onmicrosoft.com has full access to the room's messages, events and calendars.

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendar
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendarView
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/events
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/messages

The best practice is to follow the principle of least privilege. Least privilege means you give your users exactly the permissions they need. To give your users permission to access only events and calendar, you need to use the Exchange Online PowerShell module.

Set mailbox folder permission in Exchange Online PowerShell

1. Install the module

Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser

2. Connect to the Exchange Online as the admin

Import-Module ExchangeOnlineManagement
$secpasswd = ConvertTo-SecureString '<password>' -AsPlainText -Force
$user = "MartinMachacek@4wrvkx.onmicrosoft.com"

$o365cred = New-Object System.Management.Automation.PSCredential ($user, $secpasswd)

Connect-ExchangeOnline -Credential $o365cred

3. Add mailbox folder permission

Add-MailboxFolderPermission -Identity Room_ZL_5.01@4wrvkx.onmicrosoft.com:\Calendar -User "JoniS@4wrvkx.onmicrosoft.com" -AccessRights ReadItems

• The Identity parameter specifies the target mailbox and folder. The syntax is MailboxID:\ParentFolder[\SubFolder].
• The User parameter specifies who's granted permission to the mailbox folder.
• The AccessRights parameter specifies the permissions that you want to add for the user on the mailbox folder. ReadItems: The user can read items within the specified folder.

4. Disconnect from the Exchange Online

Disconnect-ExchangeOnline -Confirm:$false

Now, the user is able to access only events and calendar of the meeting room.

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendar
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/calendarView
GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/events

The attempt to read messages will fail.

GET https://graph.microsoft.com/v1.0/users/Room_ZL_5.01@4wrvkx.onmicrosoft.com/messages
{
    "error": {
        "code": "ErrorItemNotFound",
        "message": "The specified object was not found in the store., Default folder AllItems not found.",
        "innerError": {
            "date": "2023-07-12T13:17:34",
            "request-id": "c021ce81-3372-4643-b9e8-37d7cd91b952",
            "client-request-id": "687cdd14-bb96-0258-bcab-d6137326fce9"
        }
    }
}