Microsoft Graph API

Learn how to use Entra Auth Cli to authenticate and interact with Microsoft Graph API.

Overview

Microsoft Graph is the unified API for Microsoft 365, providing access to:

  • Users and groups
  • Mail and calendars
  • Files (OneDrive/SharePoint)
  • Teams and collaboration
  • Security and compliance

Base URL: https://graph.microsoft.com/v1.0/

Quick Start

Setup Profile 

  entra-auth-cli config create
# Name: graph-readonly
# Client ID: <your-app-id>
# Tenant ID: <your-tenant-id>
# Scope: https://graph.microsoft.com/User.Read

Get Token and Call API 

  TOKEN=$(entra-auth-cli get-token -p graph-readonly --silent)
curl -H "Authorization: Bearer $TOKEN" \
     https://graph.microsoft.com/v1.0/me | jq

Read User Profile

Retrieve information about the authenticated user.

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-readonly --silent)

curl -H "Authorization: Bearer $TOKEN" \
     https://graph.microsoft.com/v1.0/me | jq

Required scope: User.Read

List All Users

Retrieve a list of users in your organization.

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-admin --silent \
  --scope "https://graph.microsoft.com/User.Read.All")

curl -H "Authorization: Bearer $TOKEN" \
     'https://graph.microsoft.com/v1.0/users?$select=displayName,mail,userPrincipalName' | jq

Required scope: User.Read.All

Send Email

Send an email via Microsoft Graph.

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-mail --silent \
  --scope "https://graph.microsoft.com/Mail.Send")

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "message": {
         "subject": "Test Email",
         "body": {
           "contentType": "Text",
           "content": "This is a test email from Entra Auth Cli"
         },
         "toRecipients": [
           {
             "emailAddress": {
               "address": "user@contoso.com"
             }
           }
         ]
       },
       "saveToSentItems": "true"
     }' \
     https://graph.microsoft.com/v1.0/me/sendMail

Required scope: Mail.Send

List Calendar Events

Retrieve calendar events for the authenticated user.

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-calendar --silent \
  --scope "https://graph.microsoft.com/Calendars.Read")

curl -H "Authorization: Bearer $TOKEN" \
     'https://graph.microsoft.com/v1.0/me/calendar/events?$select=subject,start,end' | jq

Required scope: Calendars.Read

Create Calendar Event

Create a new calendar event.

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-calendar --silent \
  --scope "https://graph.microsoft.com/Calendars.ReadWrite")

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "subject": "Team Meeting",
       "body": {
         "contentType": "HTML",
         "content": "Discuss Q1 goals"
       },
       "start": {
         "dateTime": "2024-01-15T14:00:00",
         "timeZone": "UTC"
       },
       "end": {
         "dateTime": "2024-01-15T15:00:00",
         "timeZone": "UTC"
       }
     }' \
     https://graph.microsoft.com/v1.0/me/calendar/events | jq

Required scope: Calendars.ReadWrite

Common Scopes

ScopePermissionUse Case
User.ReadRead user profileBasic user info
User.Read.AllRead all usersDirectory queries
Mail.ReadRead emailEmail client
Mail.SendSend emailEmail automation
Calendars.ReadRead calendarsCalendar sync
Calendars.ReadWriteModify calendarsEvent management
Files.ReadRead filesDocument access
Files.ReadWriteModify filesFile uploads

Best Practices

Use Specific Scopes 

  # Good: Specific scope
entra-auth-cli get-token -p graph --scope "https://graph.microsoft.com/User.Read"

# Avoid: .default in scripts (requests all consented permissions)
entra-auth-cli get-token -p graph --scope "https://graph.microsoft.com/.default"

Cache Tokens 

  #!/bin/bash
TOKEN_CACHE="/tmp/graph-token.txt"

get_graph_token() {
  if [ -f "$TOKEN_CACHE" ] && entra-auth-cli discover -f "$TOKEN_CACHE" &>/dev/null; then
    cat "$TOKEN_CACHE"
  else
    entra-auth-cli get-token -p graph --silent | tee "$TOKEN_CACHE"
    chmod 600 "$TOKEN_CACHE"
  fi
}

TOKEN=$(get_graph_token)

Handle Pagination 

  #!/bin/bash
TOKEN=$(entra-auth-cli get-token -p graph-admin --silent)
URL="https://graph.microsoft.com/v1.0/users"

while [ -n "$URL" ]; do
  response=$(curl -s -H "Authorization: Bearer $TOKEN" "$URL")
  
  # Process users
  echo "$response" | jq -r '.value[].displayName'
  
  # Get next page URL
  URL=$(echo "$response" | jq -r '.["@odata.nextLink"] // empty')
done

Next Steps