Skip to main content

Permission System

The permission system in Airtrain provides a structured way to manage access to various resources and services. Most commonly used permissions are available in the permission library, making it easy to integrate with popular services like Google, Calendar, Slack, and GitHub.

Permission Structure​

Each permission in Airtrain consists of several required components:

Core Components​

  • Permission name
  • Usage method declaration
  • Data management policy
  • Authentication schemas
  • Sign-in/Sign-out methods
  • Error handling specifications

Example Permission Structure​

from airtrain import Permission, OAuth2Schema

github_permission = Permission(
    name="github_access",
    schema=OAuth2Schema,
    usage_method="Access to GitHub repositories for code review",
    data_management="Repository data cached temporarily during task execution",
    sign_in_method="oauth2_github_login",
    sign_out_method="oauth2_github_logout",
    error_message="GitHub access is required for code review. Please grant access."
)

Permission Library​

Airtrain maintains a comprehensive permission library for common services:

Common Integrations​

  • Google Services (Gmail, Drive, Calendar)
  • Collaboration Tools (Slack, Microsoft Teams)
  • Development Tools (GitHub, GitLab, Bitbucket)
  • Cloud Providers (AWS, GCP, Azure)

Using Library Permissions​

from airtrain.permissions import GoogleCalendarPermission

task_permissions = {
    "required": [GoogleCalendarPermission],
    "optional": []
}

Permission Schema​

Each permission type requires specific attributes stored in its schema:

OAuth2 Permission Example​

class OAuth2PermissionSchema(BaseSchema):
    client_id: str
    client_secret: str
    redirect_uri: str
    scope: List[str]
    auth_url: str
    token_url: str
    refresh_token_url: Optional[str]

API Key Permission Example​

class APIKeyPermissionSchema(BaseSchema):
    key_name: str
    key_location: str  # header, query, body
    key_prefix: Optional[str]
    expiration: Optional[datetime]

Authentication Methods​

Each permission must implement authentication methods:

Sign-In Method​

  • Must handle authentication flow
  • Store necessary tokens/credentials
  • Validate access
  • Handle refresh scenarios

Sign-Out Method​

  • Clean up stored credentials
  • Revoke access tokens
  • Clear cached data
  • Log out from services

Error Handling​

Permissions include specific error messaging:

Error Components​

  • User-friendly message
  • Technical details
  • Resolution steps
  • Support contact

Example Error Configuration​

error_config = {
    "user_message": "Access to Slack channels is required",
    "technical_detail": "Missing scope: channels:read",
    "resolution_steps": [
        "Click 'Grant Access' button",
        "Select required Slack channels",
        "Confirm permissions"
    ],
    "support_contact": "support@airtrain.dev"
}

Permission Usage in Tasks​

When implementing permissions in tasks:

Declaration​

@requires_permissions([
    GoogleCalendarPermission,
    SlackPermission
])
async def schedule_meeting():
    # Task implementation
    pass

Validation​

  • Permissions checked before task execution
  • Missing permissions trigger error messages
  • Invalid permissions handled gracefully

Runtime Management​

  • Permission state monitored during execution
  • Automatic refresh of expired tokens
  • Proper cleanup after task completion

Best Practices​

  1. Permission Scoping

    • Request minimum necessary permissions
    • Clearly document usage intentions
    • Implement proper cleanup

  2. Security

    • Never store raw credentials
    • Use secure token storage
    • Implement proper encryption
    • Regular permission audits

  3. User Experience

    • Clear permission requests
    • Helpful error messages
    • Simple grant/revoke process
    • Transparent usage documentation

  4. Maintenance

    • Regular permission validation
    • Update integration requirements
    • Monitor API changes
    • Version control for schemas

Next Steps​

Learn how to implement custom permissions or explore the permission library for ready-to-use integrations.