OAuth Scopes and Permissions

Overview 
 OAuth scopes provide granular, fine-grained permission control within Genesys Cloud. They define exactly what resources an application can access and what actions it can perform. Scopes are requested during authorization and enforced on every API call. 
 
 Scope Fundamentals 
 What Are Scopes?

Definition:
├─ Granular permissions for API access
├─ Limit what an application can do
├─ User consent on what app can access
├─ Enforced on every API request
└─ Principle of least privilege

Scope Format:
 resource:action
 OR
 resource:action:scope

Examples:
├─ conversations:readonly # View conversations
├─ conversations:call:add # Make calls
├─ conversations:call:control # Transfer, hold
├─ users:manage # Create/modify users
├─ routing:queue:view # View queues
└─ scheduling:manage # Manage schedules

Space-Separated Combination:
 "conversations:readonly users:readonly scheduling:manage"
 
User Sees During Authorization:
├─ App name
├─ All requested scopes
├─ What the app can do
└─ User grants all or none (all-or-nothing)

Enforcement:
├─ Every API request validated against token scopes
├─ If endpoint requires scope not in token: 403 Forbidden
├─ User permissions AND scopes both required (AND logic)
├─ Whichever is more restrictive applies
└─ Better to have both than just one
 
 
 Scope Categories 
 Conversation Management:
├─ conversations:readonly # GET conversations
├─ conversations:call:add # POST/make calls
├─ conversations:call:control # Transfer, hold, disconnect
├─ conversations:call:pull # Pull calls
├─ conversations:call:coach # Coach calls
├─ recordings:view # Access recordings
├─ recordings:download # Download recording files
├─ transcripts:readonly # View transcripts
└─ conversations:external:contact:add # Add external contacts

User Management:
├─ users:readonly # Read user info
├─ users:manage # Create/update/delete users
├─ authorization:grant:readonly # View user permissions
├─ authorization:grant:manage # Modify user permissions
├─ presence:readonly # View presence status
└─ presence:manage # Change presence

Contact Center Configuration:
├─ routing:queue:view # View queue config
├─ routing:queue:manage # Create/edit queues
├─ routing:skill:view # View skills
├─ routing:skill:manage # Manage skills
├─ directory:organization:view # View org structure
├─ telephony:phone:manage # Manage phones
├─ outbound:campaign:view # View campaigns
└─ outbound:campaign:execute # Run campaigns

Workforce Management:
├─ forecasting:readonly # View forecasts
├─ forecasting:manage # Create/edit forecasts
├─ scheduling:readonly # View schedules
├─ scheduling:manage # Create/edit schedules
├─ timeoff:view # View time-off requests
├─ timeoff:manage # Approve time-off
├─ adherence:view # View adherence
└─ adherence:manage # Manage adherence

Analytics & Reporting:
├─ analytics:conversationDetail # Detailed conversation analytics
├─ analytics:aggregate:view # Aggregated analytics
├─ quality:evaluation:view # Quality evaluations
├─ quality:evaluation:manage # Create/edit evaluations
├─ speechanalytics:data:view # Speech analytics
└─ reporting:analytics:view # Analytics reports

Integration & External:
├─ externalcontacts:manage # CRM synchronization
├─ webhooks:manage # Webhook configuration
├─ webhooks:view # View webhooks
├─ scim:write # SCIM provisioning
├─ knowledge:manage # Knowledge articles
└─ knowledge:readonly # View knowledge

Platform Management:
├─ oauth:client:view # View OAuth clients
├─ oauth:client:manage # Create/edit OAuth clients
├─ admin:org:view # View org settings
├─ admin:org:manage # Modify org settings
└─ audit:readonly # View audit logs
 
 
 Scope Selection Best Practices 
 Principle of Least Privilege:

Definition:
├─ Grant minimum scopes needed
├─ Only request what app actually uses
├─ Reduce impact if app compromised
├─ Easier to review and audit
└─ Better security posture

How to Select:

1. List API Endpoints Used:
 ├─ /conversations → conversations:readonly
 ├─ /v2/users/{id} → users:readonly
 ├─ /v2/conversations/{id}/notes → conversations:readonly
 └─ Map each endpoint to scope

2. Check Endpoint Documentation:
 ├─ Visit API Explorer
 ├─ View each endpoint
 ├─ Note required scope
 └─ Collect all scopes

3. Start with Read-Only:
 ├─ conversations:readonly (not call:add)
 ├─ users:readonly (not manage)
 ├─ Only add write scopes if needed
 └─ Safer starting point

4. Add Write Scopes Only If Needed:
 ├─ Review which operations require writes
 ├─ Add specific action scopes
 ├─ Example: call:add (not call:control)
 └─ One scope per action where possible

5. Remove Unused Scopes:
 ├─ Quarterly review
 ├─ Check OAuth client usage
 ├─ Remove unneeded scopes
 ├─ Reduce security surface
 └─ Document rationale

6. Document Your Choices:
 ├─ Why each scope is needed
 ├─ Which endpoints use it
 ├─ When to update scopes
 └─ Version control reasons

Example Selection:

App: Contact center agent desktop
├─ Endpoints needed:
│ ├─ GET /conversations → conversations:readonly
│ ├─ POST /conversations/{id}/participants/calls/transfer
│ │ → conversations:call:control
│ ├─ GET /users/me → users:readonly
│ └─ PATCH /v2/users/{id}/presence → presence:manage
│
└─ Final scopes: "conversations:readonly conversations:call:control users:readonly presence:manage"

NOT these (too permissive):
├─ conversations:manage (not needed)
├─ users:manage (not needed)
└─ conversations:call:add (can't initiate calls)
 
 
 Scope Enforcement Mechanism 
 How Scopes Are Enforced:

Every API Request Validation:

1. Client Sends Request:
 GET /api/v2/users/123
 Authorization: Bearer {access_token}

2. Genesys Validates Token:
 ├─ Token signature valid?
 ├─ Token not expired?
 ├─ Token not revoked?
 └─ Check scopes and permissions

3. Endpoint Requires:
 ├─ Endpoint /v2/users/{id} requires scope: users:readonly
 ├─ Check if token has "users:readonly" scope
 └─ Check if user has permission to read users

4. Dual Validation (Both Required):
 ├─ Must have OAuth scope: ✓ users:readonly
 ├─ Must have user permission: ✓ (has role allowing read)
 ├─ Both? → Grant access
 ├─ Only one? → 403 Forbidden
 └─ Neither? → 403 Forbidden

5. Enforce Rules:
 ├─ User has scope but not permission → 403
 ├─ User has permission but not scope → 403
 ├─ User has both → 200 OK (success)
 └─ User has neither → 403

Example Scenarios:

Scenario 1: Has Scope, Has Permission
├─ Token scope: users:readonly ✓
├─ User role permission: can read users ✓
├─ Result: 200 OK (access granted)
└─ API call succeeds

Scenario 2: Has Scope, No Permission
├─ Token scope: users:readonly ✓
├─ User role permission: cannot read users ✗
├─ Result: 403 Forbidden
└─ API call denied

Scenario 3: No Scope, Has Permission
├─ Token scope: users:readonly ✗
├─ User role permission: can read users ✓
├─ Result: 403 Forbidden
└─ API call denied

Scenario 4: No Scope, No Permission
├─ Token scope: users:readonly ✗
├─ User role permission: cannot read users ✗
├─ Result: 403 Forbidden
└─ API call denied

Example Error Response:

HTTP 403 Forbidden
{
 "error": {
 "message": "This application is not authorized to perform this action",
 "code": "PERMISSIONS_INSUFFICIENT",
 "status": 403
 }
}

Checking Available Scopes:

In API Explorer:
1. Visit: https://developer.genesys.cloud/api/rest/v2/
2. Click any endpoint
3. See "Authorization" section
4. Lists required scope
5. Copy exact scope name
 
 
 Common Scope Combinations 
 Agent Desktop Application:
 conversations:readonly
 conversations:call:control
 users:readonly
 presence:manage
 recordings:view
 (Read conversations, manage calls, see presence, view recordings)

Admin Dashboard:
 users:readonly
 routing:queue:view
 routing:skill:view
 scheduling:readonly
 analytics:conversationDetail
 (Read-only access to key admin features)

WFM Application:
 scheduling:manage
 forecasting:manage
 timeoff:manage
 adherence:manage
 users:readonly
 (Full WFM management)

Integration Service (Salesforce Sync):
 externalcontacts:manage
 users:readonly
 conversations:readonly
 (Sync contacts, read-only other data)

Chatbot / Virtual Agent:
 conversations:external:contact:add
 knowledge:readonly
 (Add external contacts, access knowledge)

Analytics Reporter:
 analytics:conversationDetail
 analytics:aggregate:view
 quality:evaluation:view
 speechanalytics:data:view
 (Read-only analytics access)

API Automation (Least Privilege):
 users:readonly (query users)
 outbound:campaign:view (check campaign status)
 (Minimal access for specific automation)
 
 
 Scope Changes & Updates 
 Adding Scopes to Existing OAuth Client:

Scenario:
├─ App previously only read conversations
├─ Now needs to transfer calls
├─ Must add conversations:call:control scope

Steps:

1. Stop Using Old Client (or keep both briefly):
 ├─ Update app configuration
 ├─ Point to updated client
 └─ Test thoroughly

2. Navigate to OAuth Client in Admin:
 ├─ Admin → Integrations → OAuth
 ├─ Find your OAuth client
 ├─ Click Edit
 └─ Select Scopes

3. Update Scopes:
 ├─ Old: "conversations:readonly"
 ├─ New: "conversations:readonly conversations:call:control"
 ├─ Add all needed scopes
 └─ Save changes

4. User Must Re-Authorize:
 ├─ For Authorization Code Grant: Yes
 ├─ Users see new permissions consent screen
 ├─ Users must grant new scope
 └─ New token includes updated scopes

5. Test Thoroughly:
 ├─ Test new functionality
 ├─ Verify old functions still work
 ├─ Check error responses
 └─ Monitor for issues

6. Gradual Rollout (Optional):
 ├─ Update small group first
 ├─ Monitor for errors
 ├─ Expand to more users
 └─ Full rollout when confident

Removing Unused Scopes:

Scenario:
├─ App no longer uses contact creation
├─ Can remove conversations:external:contact:add
├─ Reduce security surface

Steps:

1. Verify Not Used:
 ├─ Check code for usage
 ├─ Search for endpoint calls
 ├─ Verify in logs (not used)
 └─ Confirm removal safe

2. Update OAuth Client:
 ├─ Admin → Integrations → OAuth
 ├─ Click Edit
 ├─ Deselect unused scope
 └─ Save

3. No Re-Authorization Needed:
 ├─ Existing tokens still work
 ├─ New tokens won't have old scope
 ├─ Endpoints still work (user has permission)
 └─ Gradual transition

4. Monitor for Errors:
 ├─ Watch logs for 403 errors
 ├─ Verify no broken functionality
 └─ Quick rollback if issues
 
 
 Scope Testing 
 Testing Scope-Based Authorization:

Setup Test OAuth Client:

1. Create OAuth client with specific scopes
2. Authenticate with that client
3. Test that allowed endpoints work
4. Test that forbidden endpoints fail

Testing Allowed Scope:

Endpoint: GET /conversations
Scope: conversations:readonly
Token has scope: Yes

Test:
 curl -H "Authorization: Bearer {token}" \
 https://api.mypurecloud.com/api/v2/conversations
 
Expected: HTTP 200 (success)
Actual: ?

Testing Denied Scope (Negative Test):

Endpoint: POST /conversations (create)
Scope needed: conversations:manage
Token has scope: No

Test:
 curl -X POST \
 -H "Authorization: Bearer {token}" \
 https://api.mypurecloud.com/api/v2/conversations
 
Expected: HTTP 403 Forbidden
Actual: ?

Test Multiple Scopes:

Token has scopes:
├─ conversations:readonly
├─ users:readonly
└─ NOT: scheduling:manage

Tests to Run:
├─ GET /conversations → 200 (has scope)
├─ GET /users → 200 (has scope)
├─ GET /schedules → 403 (no scope)
├─ DELETE /conversations/{id} → 403 (no manage scope)
└─ DELETE /users/{id} → 403 (no manage scope)

Automated Testing:

Example Test Suite:

Test Cases:
├─ [✓] conversations:readonly allows GET
├─ [✓] conversations:readonly denies POST
├─ [✓] conversations:call:control allows transfer
├─ [✓] users:readonly allows GET /users
├─ [✓] users:readonly denies PUT /users
├─ [✓] Multiple scopes work correctly
├─ [✓] Missing scopes return 403
└─ [✓] Expired token returns 401

Before Deployment:
├─ Run all scope tests
├─ Verify expected 403s
├─ Verify expected 200s
└─ Document scope requirements
 
 
 Troubleshooting Scope Issues 
 Problem: Getting 403 Forbidden on Valid Endpoint

Check List:
┌─ Token Valid?
│ ├─ Is token expired?
│ ├─ Try making another call
│ └─ Get fresh token if needed
│
├─ Scope Correct?
│ ├─ Check API Explorer for required scope
│ ├─ Verify token has that scope
│ ├─ Look at token claims if JWT
│ └─ Add missing scope to OAuth client
│
├─ User Has Permission?
│ ├─ User role has permission?
│ ├─ Check user's roles in Admin UI
│ ├─ Check division assignments
│ └─ Add necessary role if missing
│
└─ Both Needed?
 ├─ User permission: Required
 ├─ OAuth scope: Required
 ├─ Have both? Should work
 └─ Missing one? 403 error

Example Troubleshooting:

Error: POST /v2/users returns 403
├─ Required scope: users:manage
├─ Check 1: Token has users:manage? NO ✗
│ └─ Solution: Add users:manage scope to OAuth client
│
├─ Check 2: User has create user permission? YES ✓
│ └─ OK (permission is good)
│
├─ Root Cause: Missing scope in token
├─ Solution: Update OAuth client scopes
└─ Retry after user re-authenticates

Error: GET /v2/conversations returns 403
├─ Required scope: conversations:readonly
├─ Check 1: Token has conversations:readonly? YES ✓
│ └─ OK (scope is good)
│
├─ Check 2: User has read conversations permission? NO ✗
│ └─ Solution: Add user to role with permission
│
├─ Root Cause: User lacks role permission
├─ Solution: Assign appropriate role to user
└─ Retry after role assignment takes effect

Common Mistakes:

❌ Wrong Scope Name:
├─ Requested: "conversation:view" (wrong)
├─ Correct: "conversations:readonly"
└─ Solution: Check API Explorer for exact scope

❌ Typo in Scope:
├─ Requested: "users :manage" (space)
├─ Correct: "users:manage"
└─ Solution: Check spacing carefully

❌ Missing Scope Entirely:
├─ Requested: "users:readonly" only
├─ Needed: "users:readonly users:manage"
└─ Solution: Add missing scopes

❌ Wrong Colon Format:
├─ Requested: "users-manage" (dash)
├─ Correct: "users:manage" (colon)
└─ Solution: Use colons, not dashes
 
 
 Scope Documentation 
 For Your Team:

Document Your Scopes:

Application: [App Name]
├─ conversations:readonly
│ ├─ Used for: Display conversation history
│ ├─ Endpoints: GET /v2/conversations
│ └─ Rationale: Need to show past interactions
│
├─ conversations:call:control
│ ├─ Used for: Transfer calls between agents
│ ├─ Endpoints: POST /v2/conversations/{id}/participants/calls/transfer
│ └─ Rationale: Core feature for agent desktop
│
├─ users:readonly
│ ├─ Used for: List available agents
│ ├─ Endpoints: GET /v2/users
│ └─ Rationale: Show agent list for transfers
│
└─ Updated: March 2026
 └─ Next Review: September 2026

Scope Change Log:

Date | Change | Reason
------------|---------------|----------------------------------
2026-03-01 | Added: call:control | New transfer feature
2026-01-15 | Added: users:readonly | Show agent list
2025-11-20 | Initial: conversations:readonly | Read-only access

API Endpoint to Scope Mapping:

Endpoint | Method | Scope Required
---------|--------|----------------
/v2/conversations | GET | conversations:readonly
/v2/conversations | POST | conversations:readonly (new)
/v2/conversations/{id} | GET | conversations:readonly
/v2/users | GET | users:readonly
/v2/users/{id}/presence | PATCH | presence:manage
 
 
 Key Takeaways: Chapter 5 
 
 Granular Permissions - Scopes define exactly what app can do 
 Least Privilege - Request minimum scopes needed 
 User Consent - Users see all scopes during authorization 
 Dual Enforcement - User permissions AND OAuth scopes both required 
 403 Means Missing - Either scope or permission (or both) missing 
 Standard Format - Use resource:action or resource:action:scope 
 Space-Separated - Combine multiple scopes with spaces 
 Review Regularly - Quarterly scope audits reduce security risk 
 
 
 Interview Prep: OAuth Scopes 
 
 
 
 Question 
 Answer 
 
 
 
 
 What are scopes? 
 Granular permissions defining what app can access/do 
 
 
 Scope format? 
 resource:action or resource:action:scope (e.g., conversations:readonly) 
 
 
 How combined? 
 Space-separated list (e.g., "conversations:readonly users:manage") 
 
 
 User sees scopes? 
 Yes, during authorization consent screen 
 
 
 All-or-nothing? 
 Yes, user grants all requested scopes or none 
 
 
 How enforced? 
 Every API request checked against token scopes 
 
 
 User + scope? 
 BOTH required (AND logic), not OR 
 
 
 403 means? 
 Missing scope or missing permission (or both) 
 
 
 Best practice? 
 Principle of least privilege - request minimum needed 
 
 
 How update? 
 Edit OAuth client, add/remove scopes, user must re-auth 
 
 
 
 
 Document Version 
 Chapter : 5 of 8 
 Last Updated : March 2026 
 Status : Current with OAuth 2.0 standards 
 Scope : Scope management, enforcement, best practices