Enterprise Features¶

Retrieving information¶

pyAirtable exposes a number of classes and methods for interacting with enterprise organizations. The following methods are only available on an Enterprise plan. If you call one of them against a base that is not part of an enterprise workspace, Airtable will return a 404 error, and pyAirtable will add a reminder to the exception to check your billing plan.

Api.enterprise(enterprise_account_id)[source]

⚠ This feature is only available on Enterprise billing plans.

Build an object representing an enterprise account.

Return type: Enterprise

Base.collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base collaborators.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: BaseCollaborators

Base.shares()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base shares.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: List[Info]

Workspace.collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information, collaborators, and invite links for the given workspace, caching the result.

See https://airtable.com/developers/web/api/get-workspace-collaborators

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: WorkspaceCollaborators

Enterprise.info()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information about the enterprise, caching the result.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: EnterpriseInfo

Retrieving audit logs¶

Enterprise.audit_log(*, page_size=None, page_limit=None, sort_asc=False, previous=None, next=None, start_time=None, end_time=None, user_id=None, event_type=None, model_id=None, category=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve and yield results from the Audit Log, one page of results at a time. Each result is an instance of AuditLogResponse and contains the pagination IDs returned from the API, as described in the linked documentation.

By default, the Airtable API will return up to 180 days of audit log events, going backwards from most recent. Retrieving all records may take some time, but is as straightforward as:

>>> enterprise = Enterprise("entYourEnterpriseId")
>>> events = [
...     event
...     for page in enterprise.audit_log()
...     for event in page.events
... ]

If you are creating a record of all audit log events, you probably want to start with the earliest events in the retention window and iterate chronologically. You’ll likely have a job running periodically in the background, so you’ll need some way to persist the pagination IDs retrieved from the API in case that job is interrupted and needs to be restarted.

The sample code below will use a local file to remember the next page’s ID, so that if the job is interrupted, it will resume where it left off (potentially processing some entries twice).

import os
import shelve
import pyairtable

def handle_event(event):
    print(event)

api = pyairtable.Api(os.environ["AIRTABLE_API_KEY"])
enterprise = api.enterprise(os.environ["AIRTABLE_ENTERPRISE_ID"])
persistence = shelve.open("audit_log.db")
first_page = persistence.get("next", None)

for page in enterprise.audit_log(sort_asc=True, next=first_page):
    for event in page.events:
        handle_event(event)
    persistence["next"] = page.pagination.next

For more information on any of the keyword parameters below, refer to the audit log events API documentation.

Parameters

page_size (Optional[int], default: None) – How many events per page to return (maximum 100).
page_limit (Optional[int], default: None) – How many pages to return before stopping.
sort_asc (Optional[bool], default: False) – Whether to sort in ascending order (earliest to latest) rather than descending order (latest to earliest).
previous (Optional[str], default: None) – Requests the previous page of results from the given ID. See the audit log integration guide for more information on pagination parameters.
next (Optional[str], default: None) – Requests the next page of results according to the given ID. See the audit log integration guide for more information on pagination parameters.
start_time (Union[str, date, datetime, None], default: None) – Earliest timestamp to retrieve (inclusive).
end_time (Union[str, date, datetime, None], default: None) – Latest timestamp to retrieve (inclusive).
originating_user_id – Retrieve audit log events originating from the provided user ID or IDs (maximum 100).
event_type (Union[str, Iterable[str], None], default: None) – Retrieve audit log events falling under the provided audit log event type or types (maximum 100).
model_id (Union[str, Iterable[str], None], default: None) – Retrieve audit log events taking action on, or involving, the provided model ID or IDs (maximum 100).
category (Union[str, Iterable[str], None], default: None) – Retrieve audit log events belonging to the provided audit log event category or categories.

Return type

Iterator[AuditLogResponse]

Returns

An object representing a single page of audit log results.

Managing permissions and shares¶

You can use pyAirtable to change permissions on a base or workspace via the following methods exposed on schema objects.

If for some reason you need to call these API endpoints without first retrieving schema information, you might consider calling request() directly.

Add base collaborator

>>> base.collaborators().add_user("usrUserId", "read")
>>> base.collaborators().add_group("ugpGroupId", "edit")
>>> base.collaborators().add("user", "usrUserId", "comment")

Add interface collaborator

>>> base.collaborators().interfaces[pbd].add_user("usrUserId", "read")
>>> base.collaborators().interfaces[pbd].add_group("ugpGroupId", "read")
>>> base.collaborators().interfaces[pbd].add("user", "usrUserId", "read")

Add workspace collaborator

>>> workspace.collaborators().add_user("usrUserId", "read")
>>> workspace.collaborators().add_group("ugpGroupId", "edit")
>>> workspace.collaborators().add("user", "usrUserId", "comment")

Update collaborator base permission

>>> base.collaborators().update("usrUserId", "edit")
>>> base.collaborators().update("ugpGroupId", "edit")

Update interface collaborator

>>> base.collaborators().interfaces[pbd].update("usrUserId", "edit")
>>> base.collaborators().interfaces[pbd].update("ugpGroupId", "edit")

Update workspace collaborator

>>> workspace.collaborators().update("usrUserId", "edit")
>>> workspace.collaborators().update("ugpGroupId", "edit")

Delete base collaborator

>>> base.collaborators().remove("usrUserId")
>>> base.collaborators().remove("ugpGroupId")

Delete interface collaborator

>>> base.collaborators().interfaces[pbd].remove("usrUserId")
>>> base.collaborators().interfaces[pbd].remove("ugpGroupId")

Delete workspace collaborator

>>> workspace.collaborators().remove("usrUserId")
>>> workspace.collaborators().remove("ugpGroupId")

Delete base invite

>>> base.collaborators().invite_links.via_base[0].delete()
>>> workspace.collaborators().invite_links.via_base[0].delete()

Delete interface invite

>>> base.collaborators().interfaces[pbd].invite_links[0].delete()

Delete workspace invite

>>> base.collaborators().invite_links.via_workspace[0].delete()
>>> workspace.collaborators().invite_links.via_workspace[0].delete()

Manage share

>>> share = base.shares()[0]
>>> share.disable()
>>> share.enable()

Delete share

>>> share.delete()

Update workspace restrictions

>>> r = workspace.collaborators().restrictions
>>> r.invite_creation = "unrestricted"
>>> r.share_creation = "onlyOwners"
>>> r.save()

Managing users¶

You can use pyAirtable to manage an enterprise’s users via the following methods.

Manage user

>>> user = enterprise.user("usrUserId")
>>> user.state = "deactivated"
>>> user.email = user.email.replace("@", "+deactivated@")
>>> user.save()

Logout user

>>> user.logout()

Delete user by id

>>> user.delete()

Remove user from enterprise

>>> enterprise.remove_user("usrUserId", replacement="usrOtherUserId")

Manage user membership

>>> enterprise.claim_users({"userId": "managed"})

Delete users by email

>>> enterprise.delete_users(["foo@example.com", "bar@example.com"])