0
# Access Control and Permissions
1

2
Calendar sharing, access control rules, and permission management for collaborative calendar usage. The AccessControlRule class manages who can access calendars and what level of access they have.
3

4
## Core Imports
5

6
```python
7
from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType
8
```
9

10
## Capabilities
11

12
### AccessControlRule Class
13

14
Represents Access Control List (ACL) rules for calendar permissions, controlling who can access a calendar and what they can do with it.
15

16
```python { .api }
17
class AccessControlRule:
18
    def __init__(
19
        self,
20
        role: str,
21
        scope_type: str,
22
        acl_id: str = None,
23
        scope_value: str = None
24
    ):
25
        """
26
        Create an access control rule for a calendar.
27
        
28
        Parameters:
29
        - role (str): Access level ('none', 'freeBusyReader', 'reader', 'writer', 'owner')
30
        - scope_type (str): Type of scope ('default', 'user', 'group', 'domain')
31
        - acl_id (str): Unique identifier for the ACL rule
32
        - scope_value (str): Email address or domain for user/group/domain scopes
33
        """
34

35
    @property
36
    def id(self) -> str:
37
        """
38
        Get the ACL rule ID.
39
        
40
        Returns:
41
        str: Unique identifier for the ACL rule
42
        """
43
```
44

45
### ACL Management via GoogleCalendar
46

47
Methods for managing access control rules through the main GoogleCalendar client.
48

49
```python { .api }
50
def get_acl_rules(
51
    self,
52
    calendar_id: str = None,
53
    max_results: int = None,
54
    page_token: str = None,
55
    show_deleted: bool = None,
56
    sync_token: str = None
57
):
58
    """
59
    Get access control rules for a calendar.
60
    
61
    Parameters:
62
    - calendar_id (str): Calendar identifier
63
    - max_results (int): Maximum number of rules to return
64
    - page_token (str): Token for pagination
65
    - show_deleted (bool): Whether to include deleted rules
66
    - sync_token (str): Token for incremental sync
67
    
68
    Returns:
69
    List of AccessControlRule objects
70
    """
71

72
def get_acl_rule(self, acl_id: str, calendar_id: str = None):
73
    """
74
    Get a specific access control rule.
75
    
76
    Parameters:
77
    - acl_id (str): ACL rule identifier
78
    - calendar_id (str): Calendar identifier
79
    
80
    Returns:
81
    AccessControlRule object
82
    """
83

84
def add_acl_rule(
85
    self,
86
    acl_rule,
87
    calendar_id: str = None,
88
    send_notifications: bool = None
89
):
90
    """
91
    Add an access control rule to a calendar.
92
    
93
    Parameters:
94
    - acl_rule (AccessControlRule): ACL rule to add
95
    - calendar_id (str): Calendar identifier
96
    - send_notifications (bool): Whether to send notification emails
97
    
98
    Returns:
99
    Created AccessControlRule object with assigned ID
100
    """
101

102
def update_acl_rule(
103
    self,
104
    acl_rule,
105
    acl_id: str = None,
106
    calendar_id: str = None,
107
    send_notifications: bool = None
108
):
109
    """
110
    Update an existing access control rule.
111
    
112
    Parameters:
113
    - acl_rule (AccessControlRule): Modified ACL rule
114
    - acl_id (str): ACL rule identifier
115
    - calendar_id (str): Calendar identifier
116
    - send_notifications (bool): Whether to send notification emails
117
    
118
    Returns:
119
    Updated AccessControlRule object
120
    """
121

122
def delete_acl_rule(self, acl_id: str, calendar_id: str = None):
123
    """
124
    Delete an access control rule.
125
    
126
    Parameters:
127
    - acl_id (str): ACL rule identifier
128
    - calendar_id (str): Calendar identifier
129
    """
130
```
131

132
## Access Control Constants
133

134
### ACL Roles
135

136
```python { .api }
137
class ACLRole:
138
    NONE = "none"                    # No access
139
    FREE_BUSY_READER = "freeBusyReader"  # Can see free/busy information only
140
    READER = "reader"                # Can read event details
141
    WRITER = "writer"                # Can create and modify events
142
    OWNER = "owner"                  # Full control over calendar
143
```
144

145
### ACL Scope Types
146

147
```python { .api }
148
class ACLScopeType:
149
    DEFAULT = "default"              # Default access for all users
150
    USER = "user"                    # Specific user by email
151
    GROUP = "group"                  # Google group by email
152
    DOMAIN = "domain"                # Entire domain
153
```
154

155
## Usage Examples
156

157
### Basic Calendar Sharing
158

159
```python
160
from gcsa.google_calendar import GoogleCalendar
161
from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType
162

163
gc = GoogleCalendar()
164

165
# Share calendar with specific user (read access)
166
read_rule = AccessControlRule(
167
    role=ACLRole.READER,
168
    scope_type=ACLScopeType.USER,
169
    scope_value="user@example.com"
170
)
171
gc.add_acl_rule(read_rule, calendar_id="my_calendar_id")
172

173
# Give write access to another user
174
write_rule = AccessControlRule(
175
    role=ACLRole.WRITER,
176
    scope_type=ACLScopeType.USER,
177
    scope_value="colleague@example.com"
178
)
179
gc.add_acl_rule(write_rule, calendar_id="my_calendar_id")
180
```
181

182
### Domain-Wide Sharing
183

184
```python
185
# Share calendar with entire domain (free/busy only)
186
domain_rule = AccessControlRule(
187
    role=ACLRole.FREE_BUSY_READER,
188
    scope_type=ACLScopeType.DOMAIN,
189
    scope_value="company.com"
190
)
191
gc.add_acl_rule(domain_rule, calendar_id="shared_calendar_id")
192

193
# Make calendar public (read-only)
194
public_rule = AccessControlRule(
195
    role=ACLRole.READER,
196
    scope_type=ACLScopeType.DEFAULT
197
)
198
gc.add_acl_rule(public_rule, calendar_id="public_calendar_id")
199
```
200

201
### Group-Based Sharing
202

203
```python
204
# Share with Google group
205
group_rule = AccessControlRule(
206
    role=ACLRole.WRITER,
207
    scope_type=ACLScopeType.GROUP,
208
    scope_value="team@company.com"
209
)
210
gc.add_acl_rule(group_rule, calendar_id="team_calendar_id")
211
```
212

213
### Managing Existing ACL Rules
214

215
```python
216
# List all ACL rules for a calendar
217
acl_rules = gc.get_acl_rules(calendar_id="my_calendar_id")
218
for rule in acl_rules:
219
    print(f"Rule {rule.id}: {rule.role} for {rule.scope_type} {rule.scope_value}")
220

221
# Update an existing rule
222
existing_rule = gc.get_acl_rule("rule_id", calendar_id="my_calendar_id")
223
existing_rule.role = ACLRole.WRITER  # Upgrade from reader to writer
224
gc.update_acl_rule(existing_rule, calendar_id="my_calendar_id")
225

226
# Remove access
227
gc.delete_acl_rule("rule_id", calendar_id="my_calendar_id")
228
```
229

230
### Notification Control
231

232
```python
233
# Add rule with notifications
234
new_rule = AccessControlRule(
235
    role=ACLRole.READER,
236
    scope_type=ACLScopeType.USER,
237
    scope_value="newuser@example.com"
238
)
239
gc.add_acl_rule(
240
    new_rule,
241
    calendar_id="shared_calendar",
242
    send_notifications=True  # Send email notification to user
243
)
244

245
# Update rule without notifications
246
existing_rule.role = ACLRole.WRITER
247
gc.update_acl_rule(
248
    existing_rule,
249
    calendar_id="shared_calendar",
250
    send_notifications=False  # Silent update
251
)
252
```
253

254
### Calendar Ownership Transfer
255

256
```python
257
# Transfer ownership to another user
258
owner_rule = AccessControlRule(
259
    role=ACLRole.OWNER,
260
    scope_type=ACLScopeType.USER,
261
    scope_value="newowner@example.com"
262
)
263
gc.add_acl_rule(owner_rule, calendar_id="calendar_to_transfer")
264

265
# Note: Original owner automatically becomes a writer after transfer
266
```
267

268
### Advanced ACL Management
269

270
```python
271
# Create a calendar with specific sharing settings
272
from gcsa.calendar import Calendar
273

274
# Create new calendar
275
new_calendar = Calendar(
276
    summary="Project Calendar",
277
    description="Shared project calendar"
278
)
279
created_calendar = gc.add_calendar(new_calendar)
280

281
# Set up multiple access levels
282
acl_rules = [
283
    # Project manager gets full access
284
    AccessControlRule(
285
        role=ACLRole.OWNER,
286
        scope_type=ACLScopeType.USER,
287
        scope_value="manager@company.com"
288
    ),
289
    # Team members can edit
290
    AccessControlRule(
291
        role=ACLRole.WRITER,
292
        scope_type=ACLScopeType.GROUP,
293
        scope_value="project-team@company.com"
294
    ),
295
    # Stakeholders can view
296
    AccessControlRule(
297
        role=ACLRole.READER,
298
        scope_type=ACLScopeType.GROUP,
299
        scope_value="stakeholders@company.com"
300
    ),
301
    # Company can see free/busy
302
    AccessControlRule(
303
        role=ACLRole.FREE_BUSY_READER,
304
        scope_type=ACLScopeType.DOMAIN,
305
        scope_value="company.com"
306
    )
307
]
308

309
# Apply all rules
310
for rule in acl_rules:
311
    gc.add_acl_rule(rule, calendar_id=created_calendar.id)
312
```
313

314
### Error Handling for ACL Operations
315

316
```python
317
from googleapiclient.errors import HttpError
318

319
try:
320
    # Attempt to add ACL rule
321
    rule = AccessControlRule(
322
        role=ACLRole.WRITER,
323
        scope_type=ACLScopeType.USER,
324
        scope_value="invalid@email"
325
    )
326
    gc.add_acl_rule(rule, calendar_id="calendar_id")
327
    
328
except HttpError as e:
329
    if e.resp.status == 400:
330
        print("Invalid ACL rule parameters")
331
    elif e.resp.status == 403:
332
        print("Insufficient permissions to modify ACL")
333
    elif e.resp.status == 404:
334
        print("Calendar or ACL rule not found")
335
    else:
336
        print(f"API error: {e}")
337
```
338

339
### Bulk ACL Management
340

341
```python
342
# Remove all non-owner rules from a calendar
343
acl_rules = gc.get_acl_rules(calendar_id="private_calendar")
344
for rule in acl_rules:
345
    if rule.role != ACLRole.OWNER:
346
        gc.delete_acl_rule(rule.id, calendar_id="private_calendar")
347

348
# Copy ACL from one calendar to another
349
source_rules = gc.get_acl_rules(calendar_id="source_calendar")
350
for rule in source_rules:
351
    if rule.role != ACLRole.OWNER:  # Don't copy ownership
352
        new_rule = AccessControlRule(
353
            role=rule.role,
354
            scope_type=rule.scope_type,
355
            scope_value=rule.scope_value
356
        )
357
        gc.add_acl_rule(new_rule, calendar_id="target_calendar")
358
```
359

360
Access control in GCSA provides fine-grained permission management for calendar sharing, supporting individual users, groups, domains, and public access with different levels of permissions from free/busy visibility to full ownership.