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:
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 ID | Value |
| client_id | The client ID generated by registering the app. This is shown on the overview page of the application you generated in ‘Registering An Application‘. |
| redirect_uri | This 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_type | This should be ‘code’ for the authorisation code request. |
| scope | This 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. |
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:
Smart Building Solutions & Distributor UK
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 ID | Value |
| grant_type | The text value ‘authorisation_code’. |
| code | The authorisation code value obtained in ‘Authorisation Code‘. |
| redirect_uri | This should contain the same redirection value used in ‘Authorisation Code‘. |
| client_id | The API application client ID |
| client_secret | The API application client secret generated in ‘Create A Secret‘ |
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 Key | Value |
| access_token | The API Bearer access token to use in subsequent data requests. |
| refresh_token | The refresh token to use when the access token expires. |
| expires_in | The number seconds the access token is valid for before it needs refreshing. |
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 ID | Value |
| grant_type | The text value ‘refresh_token’. |
| refresh_token | The refresh token returned by the last token request (or refresh request). |
| client_id | The API Application client ID |
| client_secret | The API application client secret generated in ‘Create A Secret‘ |
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 Key | Value |
| access_token | The API Bearer access token to use in subsequent data requests. |
| refresh_token | The refresh token to use when the access token expires. |
| expires_in | The number seconds the access token is valid for before it needs refreshing |
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