(Internal) Gem <> Microsoft Graph API permissions

🔍 Articles in This Section

Please use the following list to see additional internal articles regarding Gem Access Types & Permissions:

• (Internal) Gem email permissions: Overview
• (Internal) Gem <> Microsoft Graph API permissions (📍you are here)
• (Internal) Setting and updating a team's domain mail agent
• (Internal) Process for setting up teams using an on-premise exchange server: Nylas

Overview

Gem uses the official Microsoft Graph API to connect with systems like Outlook365 in order to provide its recruiting workflow automation functionality to end-users. Gem uses delegated permissions (not application permission) to facilitate the connection between individual users, in an interactive OAuth authorization flow, and the Gem system.

The API scopes requested by Gem are necessary to enable end-users to carry out their job-specific tasks. These scopes are organized in a hierarchy. Foundational scopes are required for users requiring access to the Gem platform.

In additional to Foundational permission, Gem offers 2 options (each with their own set of API scopes) for connecting Gem to Outlook365 in order to provide recruiting workflow automation functionality for communication with prospective candidates. The first option is Gem’s full integration; it provides the highest level of functionality. The second option is Gem’s metadata-only/limited integration; it reduces the API scopes required but provides less functionality to end-users.

Foundational API Scopes

1. openid — used to map a unique identifier to the user logging in to Gem
2. profile — used to import the user’s given name and family name
3. email — used to obtain a user’s email address. Does not grant access to a user’s mailbox; it only let’s Gem see the user’s email address. This is used for sending notification emails to users and as the ‘Reply-To’ address when sending communications to candidates through Gem.
4. User.Read — used to obtain the user’s profile photo for usage within the Gem application.
5. offline_access — allows Gem to maintain access to the above information and keep it accurate and up-to-date.

Outlook365 Option 1: Full API Scopes

1. Mail.Read — used to read messages in the user’s primary mailbox. This allows Gem to synchronize a prospective candidate’s first reply to a message sent by Gem back into the Gem system. Improves the recruiting team’s overall awareness and effectiveness.
2. Mail.Read.Shared - same as above but for mailboxes shared with the user.
3. Mail.ReadWrite - used to delete Gem messages from the user’s primary outbox and replace the Gem messages with versions without shortened links. When a Gem user sends a message to a prospective candidate, we shorten the links in the message; however, recruiters do not want the version of this message with shortened links in their outbox.
4. Mail.ReadWrite.Shared — same as above but for mailboxes shared with the user.
5. Mail.Send — allows Gem users to send messages to prospective candidates from the primary mailbox using the Gem web application.
6. Mail.Send.Shared — same as above but for mailboxes shared with the user.
7. MailboxSettings.Read — used to synchronize a user’s mailbox settings, such as preferred date format, from Outlook365 to Gem.
8. MailboxSettings.ReadWrite — used to synchronize a user’s settings, such as preferred date format, from Gem to Outlook365.
9. User.ReadWrite — used to synchronize a user’s information, such as given name, from Gem to Microsoft365.

Outlook365 Option 2: Metadata-only/Limited Scopes

1. Mail.ReadBasic — used to read metadata (metadata does not include the message body or attachments) of messages in a user’s primary mailbox. This allows Gem to record the fact that a prospective candidate replied to a message sent by Gem. Improves the recruiting team’s overall awareness and effectiveness.
2. Mail.Send — allows Gem users to send messages to prospective candidates from the primary mailbox using the Gem web application.
3. Mail.Send.Shared — same as above but for mailboxes shared with the user.

• Overview
• Foundational API Scopes
• Outlook365 Option 1: Full API Scopes
• Outlook365 Option 2: Metadata-only/Limited Scopes