Skip to content

Microsoft 365 - Credentials

Use the BotCity plugin for Microsoft Credentials to authenticate your account and be able to use Microsoft 365 services.


To be able to use this plugin, you need to have a Microsoft 365 account with a properly created and configured project.

For more details, see the Creating Microsoft 365 Credentials section.


pip install botcity-ms365-credentials-plugin

Importing the Plugin

After you installed this package, the next step is to import the package into your code and start using the functions.

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin

Setting up project credentials

First, let's authenticate our Microsoft 365 account using the project credentials created in the Creating Microsoft 365 Credentials section.

At this point, we will need the information we extracted during the process, the Application (client) ID and the Secret Value of the project.

# Instantiate the plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',

Defining scopes and authenticating

In this step, we will define the scope of the services we want to use.

To define the scopes that will be used, we will use the permissions that we added to the project as a reference.

You can create a list of scopes using the values defined in the Scopes class, the table below describes the available scopes:

Scope Description
Scopes.BASIC Basic authentication, used for User.Read, offline_access pemissions
Scopes.FILES_READ Used for Files.Read.All permission
Scopes.FILES_READ_WRITE_ALL Used for Files.ReadWrite.All permission
Scopes.SITES_READ_ALL Used for Sites.Read.All permission
Scopes.SITES_READ_WRITE_ALL Used for Sites.ReadWrite.All permission
Scopes.MAIL_READ Used for Mail.Read permission
Scopes.MAIL_SEND Used for Mail.Send permission
Scopes.MAIL_READ_WRITE Used for Mail.ReadWrite permission (read, write and send emails)


When instantiating the plugin, the list of scopes must match the permissions added to the project.

This step is essential to ensure no permission issues when using the APIs.

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin, Scopes

# Instantiate the plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
# Defining the scopes list
scopes_list = [Scopes.BASIC, Scopes.FILES_READ_WRITE_ALL, Scopes.MAIL_READ_WRITE]



The FILES_READ_WRITE_ALL scope referring to the Files.ReadWrite.All permission, is already enough to use OneDrive and Excel services.

The example scopes above would be enough for us to use OneDrive, Excel, and Outlook services.

Finishing the authentication flow


In the first run, it is necessary that the process be done manually so that the token file is generated.

For the subsequent runs, authentication is done automatically if the token file already exists and is still valid.

At this point, when running the code for the first time, a link will be displayed in the terminal to be opened in the browser.

In the opened browser, you have to log in to your Microsoft account that is being used, copy the complete URL that was generated and paste it into the terminal where you ran the code.

The generated URL will be something like this:

Authentication URL

After that, a file called o365_token.txt will be created. This file will be used for the next authentications, it is not necessary to perform this process again until the token expires.

Using Microsoft 365 services

At this point, you already have an instance of MS365CredentialsPlugin properly configured.

You can directly access the APIs through the ms365_account property, or use this plugin instance when instantiating the OneDrive, Excel, and Outlook plugins.