0
# Account Administration
1
2
Account management, user creation, role administration, SIS imports, and institutional-level operations. Comprehensive administrative functionality for Canvas account management.
3
4
## Capabilities
5
6
### User Management
7
8
Create, manage, and administer user accounts across the institution.
9
10
```python { .api }
11
class Account(CanvasObject):
12
def create_user(self, user: dict, **kwargs) -> User:
13
"""
14
Create a new user account.
15
16
Parameters:
17
- user: Dictionary with user attributes:
18
- name: User's full name (required)
19
- short_name: User's display name
20
- sortable_name: Name for sorting (Last, First)
21
- time_zone: User's time zone
22
- locale: User's locale/language
23
- birthdate: User's birthdate
24
- terms_of_use: Whether user agreed to terms
25
- skip_registration: Skip email verification
26
- pseudonym: Dictionary with login information:
27
- unique_id: Login ID (username/email)
28
- password: User password
29
- sis_user_id: SIS user identifier
30
- integration_id: Integration identifier
31
- send_confirmation: Send confirmation email
32
- communication_channel: Dictionary with communication channel:
33
- type: Channel type ('email', 'sms')
34
- address: Email address or phone number
35
- confirmation_url: Confirmation URL template
36
- skip_confirmation: Skip confirmation process
37
- force_validations: Force validation of user data
38
- enable_sis_reactivation: Enable SIS reactivation
39
40
Returns:
41
User object
42
"""
43
44
def get_users(self, **kwargs) -> PaginatedList[User]:
45
"""
46
List users in the account.
47
48
Parameters:
49
- search_term: Search term for user names or emails
50
- enrollment_type: Filter by enrollment type
51
- include: Additional data ('email', 'enrollments', 'locked', 'avatar_url', 'bio', 'custom_links')
52
- user_ids: Specific user IDs to retrieve
53
- user_id: Single user ID to retrieve
54
- sort: Sort field ('username', 'last_login', 'email', 'sis_id')
55
- order: Sort order ('asc', 'desc')
56
57
Returns:
58
Paginated list of User objects
59
"""
60
61
def delete_user(self, user, **kwargs) -> User:
62
"""
63
Delete a user from the account.
64
65
Parameters:
66
- user: User object or user ID
67
68
Returns:
69
Deleted User object
70
"""
71
72
def create_user_login(self, user, login: dict, **kwargs) -> Login:
73
"""
74
Create a login for an existing user.
75
76
Parameters:
77
- user: User object or user ID
78
- login: Dictionary with login attributes:
79
- unique_id: Login ID
80
- password: Login password
81
- sis_user_id: SIS user identifier
82
- integration_id: Integration identifier
83
- authentication_provider_id: Authentication provider ID
84
85
Returns:
86
Login object
87
"""
88
```
89
90
### Course Management
91
92
Create and manage courses at the account level.
93
94
```python { .api }
95
def create_course(self, **kwargs) -> Course:
96
"""
97
Create a new course.
98
99
Parameters:
100
- account_id: Account ID for the course
101
- course: Dictionary with course attributes:
102
- name: Course name
103
- course_code: Course code
104
- start_at: Course start date
105
- end_at: Course end date
106
- license: Course license
107
- is_public: Whether course is public
108
- is_public_to_auth_users: Whether course is public to authenticated users
109
- public_syllabus: Whether syllabus is public
110
- public_syllabus_to_auth: Whether syllabus is public to authenticated users
111
- public_description: Public course description
112
- allow_student_wiki_edits: Allow students to edit wiki
113
- allow_wiki_comments: Allow wiki comments
114
- allow_student_forum_attachments: Allow student forum attachments
115
- open_enrollment: Allow open enrollment
116
- self_enrollment: Allow self-enrollment
117
- restrict_enrollments_to_course_dates: Restrict enrollments to course dates
118
- term_id: Enrollment term ID
119
- sis_course_id: SIS course identifier
120
- integration_id: Integration identifier
121
- hide_final_grades: Hide final grades
122
- apply_assignment_group_weights: Apply assignment group weights
123
- time_zone: Course time zone
124
- blueprint: Whether course is a blueprint
125
- offer: Whether to offer the course immediately
126
- enroll_me: Whether to enroll the creating user
127
- enable_sis_reactivation: Enable SIS reactivation
128
129
Returns:
130
Course object
131
"""
132
133
def get_courses(self, **kwargs) -> PaginatedList[Course]:
134
"""
135
List courses in the account.
136
137
Parameters:
138
- with_enrollments: Include only courses with enrollments
139
- enrollment_type: Filter by enrollment type
140
- published: Filter by published status
141
- completed: Filter by completed status
142
- blueprint: Filter blueprint courses
143
- blueprint_associated: Filter courses associated with blueprints
144
- by_teachers: Filter by teacher user IDs
145
- by_subaccounts: Filter by subaccount IDs
146
- hide_enrollmentless_courses: Hide courses without enrollments
147
- state: Filter by workflow state
148
- enrollment_term_id: Filter by enrollment term
149
- search_term: Search term for course names/codes
150
- include: Additional data ('needs_grading_count', 'syllabus_body', 'public_description', 'total_scores', 'current_grading_period_scores', 'term', 'account', 'course_progress', 'sections', 'storage_quota_used_mb', 'total_students', 'passback_status', 'favorites', 'teachers', 'observed_users', 'tabs')
151
- sort: Sort field ('course_name', 'sis_course_id', 'teacher', 'account_name')
152
- order: Sort order ('asc', 'desc')
153
154
Returns:
155
Paginated list of Course objects
156
"""
157
```
158
159
### Subaccount Management
160
161
Create and manage account hierarchies.
162
163
```python { .api }
164
def create_subaccount(self, account: dict, **kwargs) -> Account:
165
"""
166
Create a subaccount.
167
168
Parameters:
169
- account: Dictionary with account attributes:
170
- name: Account name (required)
171
- sis_account_id: SIS account identifier
172
- default_time_zone: Default time zone
173
- default_storage_quota_mb: Default storage quota in MB
174
- default_user_storage_quota_mb: Default user storage quota in MB
175
- default_group_storage_quota_mb: Default group storage quota in MB
176
177
Returns:
178
Account object (subaccount)
179
"""
180
181
def get_sub_accounts(self, **kwargs) -> PaginatedList[Account]:
182
"""
183
List subaccounts.
184
185
Parameters:
186
- recursive: Include all descendant accounts
187
188
Returns:
189
Paginated list of Account objects
190
"""
191
```
192
193
### Admin User Management
194
195
Manage administrative users and their permissions.
196
197
```python { .api }
198
def create_admin(self, user_id: int, **kwargs) -> Admin:
199
"""
200
Create an admin user.
201
202
Parameters:
203
- user_id: ID of user to make admin
204
- role: Admin role name
205
- role_id: Admin role ID (alternative to role name)
206
- send_confirmation: Send confirmation email
207
208
Returns:
209
Admin object
210
"""
211
212
def get_admins(self, **kwargs) -> PaginatedList[Admin]:
213
"""
214
List account admins.
215
216
Parameters:
217
- user_id: Filter by specific user ID
218
219
Returns:
220
Paginated list of Admin objects
221
"""
222
223
def delete_admin(self, user_id: int, **kwargs) -> Admin:
224
"""
225
Remove admin privileges from a user.
226
227
Parameters:
228
- user_id: ID of user to remove admin privileges from
229
- role: Admin role to remove
230
- role_id: Admin role ID to remove
231
232
Returns:
233
Deleted Admin object
234
"""
235
```
236
237
### Role Management
238
239
Create and manage custom roles and permissions.
240
241
```python { .api }
242
def create_role(self, **kwargs) -> Role:
243
"""
244
Create a new role.
245
246
Parameters:
247
- label: Role name (required)
248
- role: Base role to inherit from
249
- permissions: Dictionary of permissions to enable/disable
250
- base_role_type: Base role type ('AccountMembership', 'StudentEnrollment', 'TeacherEnrollment', etc.)
251
252
Returns:
253
Role object
254
"""
255
256
def get_roles(self, **kwargs) -> PaginatedList[Role]:
257
"""
258
List roles in the account.
259
260
Parameters:
261
- account_id: Account ID to list roles for
262
- state: Filter by role state ('active', 'inactive')
263
- show_inherited: Show inherited roles
264
265
Returns:
266
Paginated list of Role objects
267
"""
268
269
def activate_role(self, role, **kwargs) -> Role:
270
"""
271
Activate a role.
272
273
Parameters:
274
- role: Role object or role ID
275
276
Returns:
277
Activated Role object
278
"""
279
280
def deactivate_role(self, role, **kwargs) -> Role:
281
"""
282
Deactivate a role.
283
284
Parameters:
285
- role: Role object or role ID
286
287
Returns:
288
Deactivated Role object
289
"""
290
```
291
292
### Authentication Providers
293
294
Manage authentication methods and SSO integrations.
295
296
```python { .api }
297
def add_authentication_providers(self, **kwargs) -> AuthenticationProvider:
298
"""
299
Add an authentication provider.
300
301
Parameters:
302
- auth_type: Authentication type ('cas', 'ldap', 'saml', 'facebook', 'github', 'google', 'linkedin', 'microsoft', 'openid_connect', 'twitter')
303
- auth_host: Authentication host
304
- auth_filter: Authentication filter
305
- auth_over_tls: Use authentication over TLS
306
- auth_base: Authentication base
307
- auth_username: Authentication username
308
- auth_password: Authentication password
309
- identifier_format: SAML identifier format
310
- certificate_fingerprint: Certificate fingerprint
311
- requested_authn_context: Requested authentication context
312
- sig_alg: Signature algorithm
313
- settings: Provider-specific settings
314
315
Returns:
316
AuthenticationProvider object
317
"""
318
319
def get_authentication_providers(self, **kwargs) -> PaginatedList[AuthenticationProvider]:
320
"""
321
List authentication providers.
322
323
Returns:
324
Paginated list of AuthenticationProvider objects
325
"""
326
```
327
328
### SIS Integration
329
330
Manage Student Information System imports and data synchronization.
331
332
```python { .api }
333
def create_sis_import(self, **kwargs) -> SisImport:
334
"""
335
Create a SIS import.
336
337
Parameters:
338
- import_type: Import type
339
- attachment: File attachment for import
340
- batch_mode: Enable batch mode
341
- batch_mode_term_id: Term ID for batch mode
342
- multi_term_batch_mode: Enable multi-term batch mode
343
- skip_deletes: Skip delete operations
344
- override_sis_stickiness: Override SIS stickiness
345
- add_sis_stickiness: Add SIS stickiness
346
- clear_sis_stickiness: Clear SIS stickiness
347
- diffing_data_set_identifier: Data set identifier for diffing
348
- diffing_remaster_data_set: Remaster data set for diffing
349
350
Returns:
351
SisImport object
352
"""
353
354
def get_sis_imports(self, **kwargs) -> PaginatedList[SisImport]:
355
"""
356
List SIS imports for the account.
357
358
Parameters:
359
- created_since: Filter by creation date
360
- created_before: Filter by creation date
361
- workflow_state: Filter by workflow state
362
363
Returns:
364
Paginated list of SisImport objects
365
"""
366
367
def abort_sis_import(self, sis_import, **kwargs) -> SisImport:
368
"""
369
Abort a running SIS import.
370
371
Parameters:
372
- sis_import: SisImport object or import ID
373
374
Returns:
375
Aborted SisImport object
376
"""
377
```
378
379
### Enrollment Terms
380
381
Manage academic terms and grading periods.
382
383
```python { .api }
384
def create_enrollment_term(self, **kwargs) -> EnrollmentTerm:
385
"""
386
Create an enrollment term.
387
388
Parameters:
389
- enrollment_term: Dictionary with term attributes:
390
- name: Term name (required)
391
- start_at: Term start date
392
- end_at: Term end date
393
- sis_term_id: SIS term identifier
394
- overrides: Date overrides for different enrollment types
395
396
Returns:
397
EnrollmentTerm object
398
"""
399
400
def get_enrollment_terms(self, **kwargs) -> PaginatedList[EnrollmentTerm]:
401
"""
402
List enrollment terms.
403
404
Parameters:
405
- workflow_state: Filter by workflow state
406
- include: Additional data ('overrides')
407
408
Returns:
409
Paginated list of EnrollmentTerm objects
410
"""
411
412
def create_grading_period(self, **kwargs) -> GradingPeriod:
413
"""
414
Create a grading period.
415
416
Parameters:
417
- grading_periods: List of grading period dictionaries:
418
- title: Grading period title
419
- start_date: Start date
420
- end_date: End date
421
- close_date: Close date
422
- weight: Weight for weighted grading
423
424
Returns:
425
GradingPeriod object
426
"""
427
428
def get_grading_periods(self, **kwargs) -> PaginatedList[GradingPeriod]:
429
"""List grading periods for the account."""
430
```
431
432
### Reports and Analytics
433
434
Generate and access account-level reports and analytics.
435
436
```python { .api }
437
def create_report(self, report_type: str, **kwargs) -> AccountReport:
438
"""
439
Create an account report.
440
441
Parameters:
442
- report_type: Type of report to generate
443
- parameters: Report-specific parameters
444
- start_at: Report start date
445
- end_at: Report end date
446
447
Returns:
448
AccountReport object
449
"""
450
451
def get_reports(self, **kwargs) -> PaginatedList[AccountReport]:
452
"""
453
List available reports for the account.
454
455
Returns:
456
Paginated list of AccountReport objects
457
"""
458
459
def get_report_status(self, report_type: str, report_id: int, **kwargs) -> AccountReport:
460
"""
461
Get status of a specific report.
462
463
Parameters:
464
- report_type: Report type
465
- report_id: Report ID
466
467
Returns:
468
AccountReport object with current status
469
"""
470
```
471
472
### Feature Management
473
474
Manage Canvas features and feature flags at the account level.
475
476
```python { .api }
477
def get_features(self, **kwargs) -> PaginatedList[Feature]:
478
"""
479
List features available to the account.
480
481
Returns:
482
Paginated list of Feature objects
483
"""
484
485
def get_feature_flag(self, feature, **kwargs) -> FeatureFlag:
486
"""
487
Get feature flag status.
488
489
Parameters:
490
- feature: Feature name or Feature object
491
492
Returns:
493
FeatureFlag object
494
"""
495
496
def set_feature_flag(self, feature, state: str, **kwargs) -> FeatureFlag:
497
"""
498
Set feature flag state.
499
500
Parameters:
501
- feature: Feature name or Feature object
502
- state: Feature state ('off', 'allowed', 'on')
503
504
Returns:
505
FeatureFlag object
506
"""
507
```
508
509
## Usage Examples
510
511
### Creating and Managing Users
512
513
```python
514
from canvasapi import Canvas
515
516
canvas = Canvas("https://canvas.example.com", "your-token")
517
account = canvas.get_account(1) # Root account
518
519
# Create a new user with login credentials
520
new_user = account.create_user(
521
user={
522
'name': 'John Smith',
523
'short_name': 'John',
524
'sortable_name': 'Smith, John',
525
'time_zone': 'America/New_York',
526
'locale': 'en'
527
},
528
pseudonym={
529
'unique_id': 'jsmith@university.edu',
530
'password': 'secure_password_123',
531
'sis_user_id': 'SIS123456',
532
'send_confirmation': True
533
},
534
communication_channel={
535
'type': 'email',
536
'address': 'jsmith@university.edu',
537
'skip_confirmation': False
538
}
539
)
540
541
print(f"Created user: {new_user.name} (ID: {new_user.id})")
542
543
# Search for users
544
users = account.get_users(
545
search_term='smith',
546
include=['email', 'enrollments'],
547
sort='last_login',
548
order='desc'
549
)
550
551
for user in users:
552
print(f"User: {user.name} ({user.login_id})")
553
print(f"Last login: {user.last_login}")
554
555
# Create additional login for existing user
556
additional_login = account.create_user_login(
557
user=new_user,
558
login={
559
'unique_id': 'john.smith',
560
'sis_user_id': 'ALT_SIS_123456'
561
}
562
)
563
```
564
565
### Course Creation and Management
566
567
```python
568
# Create a new course
569
new_course = account.create_course(
570
course={
571
'name': 'Introduction to Data Science',
572
'course_code': 'CS 301',
573
'start_at': '2024-01-15T00:00:00Z',
574
'end_at': '2024-05-15T23:59:59Z',
575
'time_zone': 'America/New_York',
576
'sis_course_id': 'CS301_SP2024',
577
'public_syllabus': True,
578
'allow_student_wiki_edits': True,
579
'term_id': spring_term.id
580
},
581
offer=True, # Make course available immediately
582
enroll_me=True # Enroll creating user as teacher
583
)
584
585
# Get courses with filtering
586
active_courses = account.get_courses(
587
with_enrollments=True,
588
published=True,
589
state=['available'],
590
include=['needs_grading_count', 'term', 'teachers'],
591
sort='course_name'
592
)
593
594
for course in active_courses:
595
print(f"Course: {course.name} ({course.course_code})")
596
print(f"Term: {course.term['name']}")
597
print(f"Enrollments: {course.total_students}")
598
```
599
600
### Role and Permission Management
601
602
```python
603
# Create a custom role
604
custom_role = account.create_role(
605
label='Course Assistant',
606
base_role_type='TaEnrollment',
607
permissions={
608
'read_course_content': 'enable',
609
'read_course_list': 'enable',
610
'read_question_banks': 'enable',
611
'read_reports': 'disable',
612
'manage_grades': 'enable',
613
'post_to_forum': 'enable',
614
'moderate_forum': 'disable',
615
'send_messages': 'enable',
616
'send_messages_all': 'disable'
617
}
618
)
619
620
# List all roles
621
roles = account.get_roles(show_inherited=True)
622
for role in roles:
623
print(f"Role: {role.label} (Base: {role.base_role_type})")
624
625
# Create admin user
626
admin_user = account.create_admin(
627
user_id=new_user.id,
628
role='Account Admin',
629
send_confirmation=True
630
)
631
632
print(f"Created admin: {admin_user.user['name']}")
633
634
# List current admins
635
admins = account.get_admins()
636
for admin in admins:
637
print(f"Admin: {admin.user['name']} (Role: {admin.role})")
638
```
639
640
### SIS Import Management
641
642
```python
643
# Create SIS import
644
sis_import = account.create_sis_import(
645
import_type='instructure_csv',
646
# attachment would be provided separately
647
batch_mode=True,
648
skip_deletes=False,
649
override_sis_stickiness=False
650
)
651
652
print(f"Started SIS import: {sis_import.id}")
653
print(f"Status: {sis_import.workflow_state}")
654
655
# Monitor import progress
656
import time
657
while sis_import.workflow_state in ['created', 'importing']:
658
time.sleep(30) # Wait 30 seconds
659
sis_import = account.get_sis_import(sis_import.id)
660
print(f"Import progress: {sis_import.progress}%")
661
662
if sis_import.workflow_state == 'imported':
663
print("Import completed successfully!")
664
print(f"Processed: {sis_import.data}")
665
elif sis_import.workflow_state == 'failed_with_messages':
666
print("Import failed with errors:")
667
for error in sis_import.processing_errors:
668
print(f" Error: {error}")
669
670
# List recent imports
671
recent_imports = account.get_sis_imports(
672
created_since='2024-01-01T00:00:00Z',
673
workflow_state=['imported', 'failed']
674
)
675
676
for import_obj in recent_imports:
677
print(f"Import {import_obj.id}: {import_obj.workflow_state} ({import_obj.created_at})")
678
```
679
680
### Term and Grading Period Management
681
682
```python
683
# Create enrollment terms
684
spring_term = account.create_enrollment_term(
685
enrollment_term={
686
'name': 'Spring 2024',
687
'start_at': '2024-01-15T00:00:00Z',
688
'end_at': '2024-05-15T23:59:59Z',
689
'sis_term_id': 'SP2024'
690
}
691
)
692
693
fall_term = account.create_enrollment_term(
694
enrollment_term={
695
'name': 'Fall 2024',
696
'start_at': '2024-08-15T00:00:00Z',
697
'end_at': '2024-12-15T23:59:59Z',
698
'sis_term_id': 'FA2024'
699
}
700
)
701
702
# Create grading periods for the term
703
grading_periods = account.create_grading_period(
704
grading_periods=[
705
{
706
'title': 'First Quarter',
707
'start_date': '2024-01-15',
708
'end_date': '2024-03-15',
709
'close_date': '2024-03-22',
710
'weight': 25
711
},
712
{
713
'title': 'Second Quarter',
714
'start_date': '2024-03-16',
715
'end_date': '2024-05-15',
716
'close_date': '2024-05-22',
717
'weight': 25
718
}
719
]
720
)
721
722
# List all terms
723
terms = account.get_enrollment_terms(include=['overrides'])
724
for term in terms:
725
print(f"Term: {term.name} ({term.start_at} - {term.end_at})")
726
```
727
728
### Report Generation
729
730
```python
731
# Generate student enrollment report
732
enrollment_report = account.create_report(
733
report_type='student_assignment_outcome_map_csv',
734
parameters={
735
'enrollment_term_id': spring_term.id,
736
'include_deleted': False
737
}
738
)
739
740
# Generate course usage report
741
usage_report = account.create_report(
742
report_type='course_storage_csv',
743
start_at='2024-01-01T00:00:00Z',
744
end_at='2024-12-31T23:59:59Z'
745
)
746
747
# Check report status
748
while usage_report.workflow_state == 'running':
749
time.sleep(60) # Wait 1 minute
750
usage_report = account.get_report_status('course_storage_csv', usage_report.id)
751
print(f"Report progress: {usage_report.progress}%")
752
753
if usage_report.workflow_state == 'complete':
754
print(f"Report completed: {usage_report.file_url}")
755
# Download report file
756
import requests
757
response = requests.get(usage_report.file_url)
758
with open('course_usage_report.csv', 'wb') as f:
759
f.write(response.content)
760
```