1. Home
  2. OSS Drivers & Modules
  3. ossEasyAPI: O365 Outlook Calendar API

ossEasyAPI: O365 Outlook Calendar API

Introduction

This is a guide to accessing the Microsoft Office 365 Outlook calendar REST API.

Requirements

The user must also have a valid Online Microsoft Office 365 account with suitable privileges to support Outlook API access.

Overview

To be able to access calendars using the Microsoft Outlook Mail API the user must first register an application to access the API.
The user must then generate an authorization code using a manual process.
This authorization code is then used in a token request which returns an access token and a refresh token.
The access token can then be used in API data requests to access the calendar.
This access token will expire, usually after one hour.
The refresh token is then used to obtain a new access token and refresh token.
The complete process is described in the following Microsoft documentation:

https://docs.microsoft.com/en-us/outlook/rest/get-started

The descriptions in this document are valid as of November 2019. Updates to the Microsoft API or web portal may mean that this guide does not reflect the latest procedures. Please refer to the latest Microsoft documentation for up to date information.


Registering an Application

To be able to register an application you will need your Microsoft account login credentials. These are usually the same as the ones used to login to the Microsoft Office online portal.

Create The Application

To register and configure an application that can access the Outlook Mail API log into the Microsoft Azure Directory admin center using your Microsoft account credentials:

https://aad.portal.azure.com/

Navigate to ‘All services’ (in the left hand column) and then select ‘App registrations’ (in the main list of services).
On the app registrations page click on the ‘New registration’ option.
Give the application a name that describes the reason for access in the API, (such as ‘View Room Bookings’).
Select the following supported account type:

Accounts in any organizational directory (Any Azure AD directory – Multitenant)

For a redirect URI select a web site that you can trust as this is where the authorisation code will be sent to in a HTTP request. For example use https://onesight.solutions.
Click on the ‘Register’ button to create the application.
On the application overview page you will see an ‘Application (client) ID’ value. You will need this client ID value in the following sections.

Configure The Application Permissions

Once the application has been created you must update the permissions so it can access the data you require via the API.
Go to the overview page for the application you have created and click on the ‘View API permissions’ button.
Click on the ‘Add a permission’ button.
Under the ‘Microsoft APIs’ tab click on ‘Microsoft Graph’ then click on ‘Delegated permissions’.
There will now be a long list of possible permissions.
To be able to read Outlook calendar event data you should expand the ‘Calendars’ section and make sure the ‘Calendars.Read’ and ‘Calendars.Read.Shared’ options are ticked.
Then click the ‘Add permissions’ button at the bottom of the page.

Create A Secret

Return to the main application overview page and click on the ‘Certificates & Secrets’ option in the near left column.
Click on the ‘New client secret’ button.
Enter a description of this secret value, (this isn’t important, it’s just for identification).
Enter an expiry period.
Click the ‘Add’ button.
A new secret value will be generated.
You will need this value for ‘Initial Token Request‘, (and ‘Token Refresh‘).


Authorisation Code

Create API authorisation code URL

To generate an API authorisation code you must first construct a special URL.
This URL begins with the following text:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize

This is followed by the parameters described in Table 1.

Parameter IDValue
client_idThe client ID generated by registering the app. This is shown on the overview
page of the application you generated in ‘Registering An Application‘.
redirect_uriThis must be the redirect URI specified when creating the application. It can be
viewed or changed in the ‘Authentication’ section of the application registration
portal. This URL text must be ‘escaped’ to remove certain invalid characters. See
the example below for guidance.
response_typeThis should be ‘code’ for the authorisation code request.
scopeThis contains the list of permissions that you configured for the application plus
the ‘offline_access’ scope which is required to obtain a refresh token. These
values are separated by plus (‘+’) signs.
Table 1: Authorisation Code URL Parameters

API Authorisation Code URL Example

The following is an example of an authorisation code URL:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<CLIENT-ID>&redirect_uri=https%3A%2F%2Fonesight.solutions &response_type=code&scope= offline_access+Calendars.Read+Calendars.Read.Shared

This should be one continuous line, but has be divided for clarity. The ‘<CLIENT-ID>’ section should be replaced with your own application client ID. The redirect_uri text is an example of the https://onesight.solutions URL that has been escaped. Change the scope values if you have selected different permissions, (but keep ‘offline_access’).

Use the URL to generate the Authorisation Code

Copy the URL you have created as one continuous line and paste it into a web browser address bar, (it is recommended to use the Google Chrome web browser).
This will take you to a Microsoft login page. You will need to log into the Microsoft Office account that you used to set up the application.
Once logged in you should be prompted to accept a set of permissions. If the permissions are what you expected then click the ‘Accept’ button.

This will redirect the web browser to the redirect URL you specified, but followed by a new set of parameters which contain the required API authorisation code.
To extract the authorisation code find the ‘?code=’ text in this URL. The code starts after the equals (‘=’) sign and ends at the next ampersand (‘&’) sign. You must copy the text in between these characters. (Everything else you can ignore).
This resulting URL usually takes the following form:

Home

It is recommended that you copy and paste the whole URL into a text editor (such as Notepad) and then edit it to extract the code in the editor.
You should end up with a long 600 – 700 character line of text that includes letters, numbers, underscores (‘_’) and minus signs (‘-‘), but should not contain ampersand (‘&’) or equals (‘=’) characters.

Authorisation Code Expiry

Microsoft authorisation codes are only valid for around 10 minutes, so the next step – the initial token request – must be completed in this time or another code will need to be generated, by repeating the process described in this section.
Additionally, authorisation codes can only be used once to generate tokens, then those tokens must be refreshed using the refresh token to continue accessing the API. If the tokens are lost then the authorisation code must be regenerated and new tokens obtained.


Initial Token Request

Token Request

Once you have an API authorisation code you can use it to get access tokens.
The token request requires a HTTP POST request to the following URL:

https://login.microsoftonline.com/common/oauth2/v2.0/token

The following HTTP headers must be included in the request:

Accept: application/json

Content-Type: application/x-www-form-urlencoded

The HTTP POST body data must include the parameters described in Table 2.

Parameter IDValue
grant_typeThe text value ‘authorisation_code’.
codeThe authorisation code value obtained in ‘Authorisation Code‘.
redirect_uriThis should contain the same redirection value
used in ‘Authorisation Code‘.
client_idThe API application client ID
client_secretThe API application client secret generated in
Create A Secret
Table 2: Token Request Parameters

This should result in a request body of the following form

grant_type=authorisation_code&code=<AUTHORISATION-CODE>&redirect_uri=https%3A%2F%2Fonesight.solutions&client_id=<CLIENT-ID>&client_secret=<CLIENT-SECRET>

Note that this text should be used as a single, continuous line, (but has been divided for clarity). The angle bracket sections (‘<…>’) should be replaced with the values from your application.

Token Response

The token request will return a JSON data response.
This JSON data should contain the fields described in Table 3.

Field KeyValue
access_tokenThe API Bearer access token to use in subsequent data requests.
refresh_tokenThe refresh token to use when the access token expires.
expires_inThe number seconds the access token is valid for before it needs refreshing.
Table 3: Token Response Fields

Other fields can be ignored.

Limitations

As the authorisation code will expire after around 10 minutes this initial token request should be made within this time or another authorisation code must be generated.
You should ensure that you save the tokens returned in the token response as the authorisation code can be used only once. If these tokens are lost then a new authorisation code must be generated.
Access tokens have a limited lifetime, specified by the ‘expires_in’ return field. This is usually around 1 hour. Once the access token has expired then a new access token must be generated using the refresh token, as described in ‘Token Refresh‘.


Event List Request

Data Request

Once you have an API access token you can use it to request API data.
This section will describe how to get a list of calendar events, the Microsoft Graph REST API reference describes the many other requests that are available.
Reading event list data requires a HTTP GET request to the following URL:

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

The following HTTP headers must be included in the request:

Accept: application/json

Authorisation: Bearer <ACCESS-TOKEN>

Where the ‘<ACCESS-TOKEN>’ section must be replaced with the access token received from the token request in ‘Initial Token Request‘, (or the refresh token request in ‘Token Refresh‘).

Note that a number of parameters can be added to the request URL to select a specific set of events (e.g. start and end times). These parameters are described in the Microsoft Graph calendar resource API reference.

Data Response

The event list request will return a JSON data response.
This JSON data will contain an array of event objects.
Each event object will contain a number of fields which are described in the Microsoft Graph event resource API reference.


Token Refresh

Token Refresh Request

API access tokens periodically expire and need to be refreshed to obtain new tokens.
This token refresh request requires a HTTP POST request to the following URL:

https://login.microsoftonline.com/common/oauth2/v2.0/token

The following HTTP headers must be included in the request:

Accept: application/json

Content-Type: application/x-www-form-urlencoded

The HTTP POST body data must include the parameters described in Table 4.

Parameter IDValue
grant_typeThe text value ‘refresh_token’.
refresh_tokenThe refresh token returned by the last token request
(or refresh request).
client_idThe API Application client ID
client_secretThe API application client secret generated in ‘Create A Secret
Table 4: Token Refresh Request Parameters

This should result in a request body of the following form:

grant_type=refresh_token

&refresh_token=<REFRESH-TOKEN>

&client_id=<CLIENT-ID>

&client_secret=<CLIENT-SECRET>

Note that this text should be used as a single, continuous line, (but has been divided for clarity). The angle bracket sections (‘<…>’) should be replaced with the values from your application.

Token Refresh Request

The token refresh request will return a JSON data response.
This JSON data should contain the fields described in Table 5.

Field KeyValue
access_tokenThe API Bearer access token to use in subsequent data requests.
refresh_tokenThe refresh token to use when the access token expires.
expires_inThe number seconds the access token is valid for before it needs refreshing
Table 5: Token Refresh Response Fields

Other fields can be ignored.


References

The following is a list of useful references:

• Overview of using the Outlook REST APIs:
https://docs.microsoft.com/en-us/outlook/rest/get-started

• Microsoft Graph REST API Reference:
https://docs.microsoft.com/en-us/graph/api/overview

• Microsoft Graph REST API Outlook Calendar Resource Reference:
https://docs.microsoft.com/en-us/graph/api/resources/calendar

• Microsoft Graph REST API Outlook Event Resource Reference:
https://docs.microsoft.com/en-us/graph/api/resources/event

Updated on June 13, 2023

Was this article helpful?

Related Articles

Existing Customer?
Need some technical support from the One Sight team?
CONTACT SUPPORT