OAuth Scopes Deep Dive
Master APS OAuth scopes with real-world combinations, security best practices, and comprehensive permission matrices for all APS services.
Essential Scopes Quick Reference
2-Legged (App-Only)
bucket:create bucket:read Create and manage OSS buckets
data:read data:write data:create Full file management
code:all Model Derivative translations
3-Legged (User Context)
user-profile:read Access user information
account:read account:write Manage ACC/BIM 360 projects
viewables:read View translated models
Complete Scope Reference
Data Management (OSS)
| Scope | Permission | Use Case | Auth Type |
|---|---|---|---|
| bucket:create | Create new buckets | Initial app setup | 2-legged |
| bucket:read | List buckets and details | Browse storage | 2-legged |
| bucket:update | Modify bucket settings | Change retention policy | 2-legged |
| bucket:delete | Delete buckets | Cleanup operations | 2-legged |
| data:read | Download objects | File access, backups | 2-legged |
| data:write | Upload, modify objects | File updates | 2-legged |
| data:create | Create new objects | Initial file upload | 2-legged |
Model Derivative
| Scope | Permission | Use Case | Auth Type |
|---|---|---|---|
| code:all | Full translation access | Complete workflows | 2-legged |
| viewables:read | Access translated models | Viewer integration | 3-legged |
User & Account Management
| Scope | Permission | Use Case | Auth Type |
|---|---|---|---|
| user-profile:read | Read user details | User identification | 3-legged |
| account:read | Access ACC/BIM 360 projects | Project browsing | 3-legged |
| account:write | Modify project data | Project management | 3-legged |
Real-World Scope Combinations
File Upload & Translation Service
For applications that accept user files, translate them, and serve the results.
bucket:create bucket:read data:create data:write data:read code:all RAPS command:
raps auth login --scopes="bucket:create bucket:read data:create data:write data:read code:all" ACC Project Integration
For apps that integrate with ACC/BIM 360 projects and need user context.
user-profile:read account:read account:write data:read viewables:read RAPS command:
raps auth login --three-legged --scopes="user-profile:read account:read account:write data:read viewables:read" Viewer-Only Application
For applications that only need to display translated models.
viewables:read RAPS command:
raps auth login --three-legged --scopes="viewables:read" CI/CD Pipeline
For automated build systems that process CAD files.
bucket:read data:create data:read code:all RAPS command:
raps auth login --scopes="bucket:read data:create data:read code:all" Security Best Practices
⚠️ Security Don'ts
- ✗ Don't request more scopes than needed
- ✗ Don't use 3-legged tokens for server-side operations
- ✗ Don't store refresh tokens in frontend apps
- ✗ Don't share tokens between environments
✅ Security Best Practices
- ✓ Use principle of least privilege
- ✓ Rotate credentials regularly
- ✓ Use different apps for different environments
- ✓ Monitor token usage and expiration
RAPS Security Features:
- • Automatic token refresh
- • Secure credential storage (OS keyring)
- • Scope validation before requests
- • Token expiration warnings
2-Legged vs 3-Legged OAuth
2-Legged (App-Only)
When to Use:
- • Server-side applications
- • CI/CD pipelines
- • Background processing
- • File storage operations
Available Scopes:
- •
bucket:*- All bucket operations - •
data:*- All file operations - •
code:all- Model translation
RAPS Example:
raps auth login
raps upload myfile.dwg
raps translate myfile.dwg3-Legged (User Context)
When to Use:
- • Web applications
- • Mobile apps
- • User-specific data access
- • ACC/BIM 360 integration
Additional Scopes:
- •
user-profile:read- User info - •
account:*- ACC projects - •
viewables:read- Viewer access
RAPS Example:
raps auth login --three-legged
raps account projects
raps view project-file.rvtCommon Scope Issues
403 Forbidden: Insufficient privileges
Your token doesn't have the required scopes.
# Check current scopes
raps auth scopes
# Login with additional scopes
raps auth login --scopes="data:read data:write code:all"Can't access ACC/BIM 360 projects
You need 3-legged authentication with account scopes.
# Use 3-legged auth for user context
raps auth login --three-legged --scopes="account:read user-profile:read"Translation jobs fail with permissions error
Model Derivative requires both data access and code:all scope.
# Ensure you have both data and translation scopes
raps auth login --scopes="data:read code:all"