1# API Permissions Guide
2 
3This document explains how to configure and manage API permissions for your Microsoft Entra app registration.
4 
5## Permission Types
6 
7### Delegated Permissions (User Context)
8 
9**What:** Application acts on behalf of a signed-in user
10 
11**When to use:**
12- User is present and can consent
13- App needs to access resources as the user
14- Interactive authentication flows
15 
16**Examples:**
17- Read user's email
18- Update user's calendar
19- Access user's OneDrive files
20 
21**Scope format:** User must consent (or admin pre-consents)
22 
23### Application Permissions (App Context)
24 
25**What:** Application acts with its own identity (no user)
26 
27**When to use:**
28- Background services, daemons
29- Scheduled jobs
30- API-to-API calls without user
31 
32**Examples:**
33- Read all users in organization
34- Send mail as any user
35- Access all SharePoint sites
36 
37**Requirement:** Always requires admin consent
38 
39## Permission Scopes
40 
41### Understanding Scopes
42 
43**Scope:** A string that defines what access is granted
44 
45**Format:**
46```
47{resource}/{permission_name}
48 
49Examples:
50https://graph.microsoft.com/User.Read
51https://graph.microsoft.com/Mail.Send
52api://myapi-id/access_as_user
53```
54 
55### .default Scope
56 
57Special scope that includes all configured permissions:
58 
59```
60https://graph.microsoft.com/.default
61api://your-api-id/.default
62```
63 
64**When to use:**
65- Client credentials flow (always)
66- Want all pre-configured permissions
67- Migrating from v1.0 endpoint
68 
69## Microsoft Graph Permissions
70 
71### Common Delegated Permissions
72 
73| Permission | What it allows | Admin Consent Required |
74|------------|---------------|----------------------|
75| `User.Read` | Read signed-in user's profile | No |
76| `User.ReadWrite` | Read and update user profile | No |
77| `User.ReadBasic.All` | Read basic info of all users | No |
78| `User.Read.All` | Read all users' full profiles | Yes |
79| `Mail.Read` | Read user's mail | No |
80| `Mail.ReadWrite` | Read and write user's mail | No |
81| `Mail.Send` | Send mail as user | No |
82| `Calendars.Read` | Read user's calendars | No |
83| `Calendars.ReadWrite` | Read and write calendars | No |
84| `Files.Read.All` | Read all files user can access | No |
85| `Sites.Read.All` | Read items in all site collections | Yes |
86| `Directory.Read.All` | Read directory data | Yes |
87| `Directory.ReadWrite.All` | Read and write directory data | Yes |
88 
89### Common Application Permissions
90 
91| Permission | What it allows | Admin Consent Required |
92|------------|---------------|----------------------|
93| `User.Read.All` | Read all users' full profiles | Yes (Always) |
94| `User.ReadWrite.All` | Read and write all users' profiles | Yes (Always) |
95| `Mail.Read` | Read mail in all mailboxes | Yes (Always) |
96| `Mail.Send` | Send mail as any user | Yes (Always) |
97| `Calendars.Read` | Read calendars in all mailboxes | Yes (Always) |
98| `Directory.Read.All` | Read directory data | Yes (Always) |
99| `Directory.ReadWrite.All` | Read and write directory data | Yes (Always) |
100| `Group.ReadWrite.All` | Read and write all groups | Yes (Always) |
101 
102## Adding Permissions
103 
104### Azure Portal Method
105 
1061. Navigate to your app registration
1072. Click **"API permissions"** in left menu
1083. Click **"+ Add a permission"**
1094. Choose API source:
110   - **Microsoft APIs** (Graph, Office 365, etc.)
111   - **APIs my organization uses** (custom APIs)
112   - **My APIs** (your own APIs)
113 
1145. Select permission type:
115   - **Delegated permissions** (user context)
116   - **Application permissions** (app context)
117 
1186. Search and select permissions
1197. Click **"Add permissions"**
120 
121See [cli-commands.md](cli-commands.md) for az cli commands to add API permissions programmatically.
122 
123## Finding Permission IDs
124 
125### Method 1: Azure Portal
126 
1271. Go to Microsoft Entra ID → Enterprise applications
1282. Search for "Microsoft Graph"
1293. Click on it → Permissions
1304. Browse available permissions and copy IDs
131 
132### Method 2: Microsoft Graph Explorer
133 
1341. Visit https://developer.microsoft.com/graph/graph-explorer
1352. Click "Modify permissions"
1363. Browse and view permission details
137 
138### Method 3: Microsoft Documentation
139 
140Visit: https://learn.microsoft.com/en-us/graph/permissions-reference
141 
142### Method 4: Azure CLI Query
143 
144```bash
145# List all Graph permissions (warning: long output)
146az ad sp list --filter "appId eq '00000003-0000-0000-c000-000000000000'" \
147  --query "[0].{delegated:oauth2PermissionScopes,application:appRoles}" -o json
148```
149 
150## Granting Admin Consent
151 
152### When Admin Consent is Required
153 
154**Always required for:**
155- All application permissions
156- High-privilege delegated permissions
157- When organization disables user consent
158 
159**Examples requiring admin consent:**
160- `User.Read.All` (read all users)
161- `Directory.Read.All` (read directory)
162- `Mail.Read` (application permission)
163- `Sites.Read.All` (read all SharePoint sites)
164 
165### How to Grant Admin Consent
166 
167**Portal Method:**
1681. Go to API permissions
1692. Click **"Grant admin consent for [Your Org]"**
1703. Confirm the action
1714. Check for green checkmarks next to permissions
172 
173**CLI Method:**
174```bash
175az ad app permission admin-consent --id $APP_ID
176```
177 
178### Verifying Consent Status
179 
180**Portal:** Look for green checkmarks in "Status" column
181 
182**CLI:**
183```bash
184az ad app permission list --id $APP_ID
185```
186 
187Look for `consentType: "AllPrincipals"` (admin consented)
188 
189## Custom API Permissions
190 
191### Exposing Your API
192 
193If you're building an API that other apps will call:
194 
1951. In your API's app registration, go to **"Expose an API"**
1962. Set **Application ID URI**: `api://your-api-id`
1973. Click **"+ Add a scope"**
1984. Configure scope:
199   - **Scope name:** `access_as_user`
200   - **Who can consent:** Admins and users
201   - **Display name:** "Access MyAPI as user"
202   - **Description:** Clear description of what this allows
2035. Click **"Add scope"**
204 
205## Effective Permissions
206 
207### User + App Permissions
208 
209**Delegated permissions:** Intersection of user's permissions and app's permissions
210 
211Example:
212- User can: Read all users
213- App granted: User.Read.All
214- **Effective:** Read all users ✅
215 
216- User can: Only read their own profile
217- App granted: User.Read.All
218- **Effective:** Only read own profile (limited by user's rights)
219 
220**Application permissions:** Only app's permissions matter (no user context)
221 
222## Troubleshooting Permissions
223 
224### "Insufficient privileges" Error
225 
226**Causes:**
227- Permission not added to app registration
228- Admin consent not granted
229- User lacks permission in directory
230- Accessing resource outside permission scope
231 
232**Solutions:**
2331. Check API permissions in portal
2342. Grant admin consent if needed
2353. Verify user has access to resource
2364. Use correct permission scope
237 
238### "Consent required" Error
239 
240**Causes:**
241- User hasn't consented to permissions
242- Admin consent required but not granted
243- Token obtained before permission added
244 
245**Solutions:**
2461. Request user consent (interactive flow)
2472. Admin grants consent (portal or CLI)
2483. Acquire new token after adding permissions
249 
250### Permission Appears Granted but Doesn't Work
251 
252**Possible issues:**
253- Using old cached token (get new one)
254- Permission is delegated but user lacks rights
255- API requires additional configuration
256- Permission deprecated (use new one)
257 
258**Debug steps:**
2591. Decode access token: https://jwt.ms
2602. Check `scp` claim (delegated) or `roles` claim (application)
2613. Verify permission is present in token
2624. Check if permission is correct type (delegated vs application)
263 
264## Permission Best Practices
265 
266### Development
267 
268✅ **Do:**
269- Start with minimal permissions
270- Add incrementally as features require
271- Test with non-admin accounts
272- Document why each permission is needed
273 
274❌ **Don't:**
275- Request all permissions "just in case"
276- Use admin account for testing only
277- Forget to grant admin consent for app permissions
278 
279### Production
280 
281✅ **Do:**
282- Review permissions quarterly
283- Remove unused permissions
284- Use least privilege principle
285- Monitor permission usage
286- Document all permissions in README
287 
288❌ **Don't:**
289- Grant excessive permissions for convenience
290- Use application permissions when delegated would work
291- Forget to rotate admin consent approvals
292 
293### Security
294 
295✅ **Do:**
296- Prefer delegated over application permissions
297- Implement proper scope validation
298- Log permission usage
299- Handle consent errors gracefully
300 
301❌ **Don't:**
302- Hardcode permission scopes in multiple places
303- Skip token validation
304- Ignore scope mismatches
305- Cache permissions indefinitely
306 
307## Reference Tables
308 
309### Microsoft Graph Permission IDs
310 
311**Delegated Permissions:**
312```
313User.Read                     : e1fe6dd8-ba31-4d61-89e7-88639da4683d
314User.ReadWrite                : b4e74841-8e56-480b-be8b-910348b18b4c
315User.ReadBasic.All            : b340eb25-3456-403f-be2f-af7a0d370277
316Mail.Read                     : 570282fd-fa5c-430d-a7fd-fc8dc98a9dca
317Mail.ReadWrite                : 024d486e-b451-40bb-833d-3e66d98c5c73
318Mail.Send                     : e383f46e-2787-4529-855e-0e479a3ffac0
319Calendars.Read                : 465a38f9-76ea-45b9-9f34-9e8b0d4b0b42
320Calendars.ReadWrite           : 1ec239c2-d7c9-4623-a91a-a9775856bb36
321Files.Read.All                : df85f4d6-205c-4ac5-a5ea-6bf408dba283
322```
323 
324**Application Permissions:**
325```
326User.Read.All                 : df021288-bdef-4463-88db-98f22de89214
327User.ReadWrite.All            : 741f803b-c850-494e-b5df-cde7c675a1ca
328Mail.Read                     : 810c84a8-4a9e-49e6-bf7d-12d183f40d01
329Mail.Send                     : b633e1c5-b582-4048-a93e-9f11b44c7e96
330Directory.Read.All            : 7ab1d382-f21e-4acd-a863-ba3e13f7da61
331Directory.ReadWrite.All       : 19dbc75e-c2e2-444c-a770-ec69d8559fc7
332```
333 
334**Note:** Permission IDs may change. Always verify against the official [Microsoft Graph Permissions Reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for the most current values.
335 
336## Additional Resources
337 
338- [Microsoft Graph Permissions Reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
339- [Permission Types](https://learn.microsoft.com/en-us/entra/identity-platform/permissions-consent-overview)
340- [Admin Consent Workflow](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-admin-consent-workflow)
341- [Consent Framework](https://learn.microsoft.com/en-us/entra/identity-platform/consent-framework)
342