0
# Authentication
1

2
Authentication classes for Webflow API integration, providing token-based authentication with proper API versioning headers required by Webflow's API.
3

4
## Capabilities
5

6
### Webflow Authentication Mixin
7

8
Mixin class that adds Webflow-specific API version headers to authentication. Webflow requires an "accept-version" header for API compatibility.
9

10
```python { .api }
11
class WebflowAuthMixin:
12
    """Mixin for adding Webflow API version headers to authentication."""
13
    
14
    def __init__(self, *, accept_version_header: str = "accept-version", accept_version: str, **kwargs):
15
        """
16
        Initialize Webflow authentication mixin.
17
        
18
        Parameters:
19
        - accept_version_header: Header name for API version (default: "accept-version")
20
        - accept_version: API version string (e.g., "1.0.0")
21
        - **kwargs: Additional arguments passed to parent class
22
        """
23
    
24
    def get_auth_header(self) -> Mapping[str, Any]:
25
        """
26
        Get authentication headers including API version.
27
        
28
        Returns:
29
        Dictionary with authentication headers plus accept-version header
30
        """
31
```
32

33
### Webflow Token Authenticator
34

35
Complete authenticator for Webflow API that combines token authentication with required API versioning headers.
36

37
```python { .api }
38
class WebflowTokenAuthenticator(WebflowAuthMixin, TokenAuthenticator):
39
    """Token-based authenticator for Webflow API with version headers."""
40
```
41

42
## Usage Examples
43

44
### Creating an Authenticator
45

46
```python
47
from source_webflow.auth import WebflowTokenAuthenticator
48

49
# Create authenticator with API token
50
auth = WebflowTokenAuthenticator(
51
    token="your_webflow_api_token",
52
    accept_version="1.0.0"
53
)
54

55
# The authenticator will automatically include both:
56
# - Authorization: Bearer your_webflow_api_token
57
# - accept-version: 1.0.0
58
```
59

60
### Using with HTTP Requests
61

62
```python
63
from source_webflow.auth import WebflowTokenAuthenticator
64
import requests
65

66
# Create authenticator
67
auth = WebflowTokenAuthenticator(
68
    token="your_api_token",
69
    accept_version="1.0.0"
70
)
71

72
# Get headers for manual requests
73
headers = auth.get_auth_header()
74
print(headers)
75
# Output: {
76
#   'Authorization': 'Bearer your_api_token',
77
#   'accept-version': '1.0.0'
78
# }
79

80
# Use with requests
81
response = requests.get(
82
    "https://api.webflow.com/sites/your_site_id/collections",
83
    headers=headers
84
)
85
```
86

87
### Custom Version Header
88

89
```python
90
from source_webflow.auth import WebflowTokenAuthenticator
91

92
# Use custom version header name (uncommon)
93
auth = WebflowTokenAuthenticator(
94
    token="your_api_token",
95
    accept_version="1.0.0",
96
    accept_version_header="api-version"  # Custom header name
97
)
98
```
99

100
## Authentication Flow
101

102
1. **Token Validation**: The API token is validated when first used in API calls
103
2. **Header Injection**: Both Authorization and accept-version headers are automatically added
104
3. **API Compatibility**: The accept-version header ensures compatibility with Webflow's API versioning
105

106
## Configuration Requirements
107

108
### API Token
109

110
Obtain a Webflow API token:
111
1. Log into your Webflow account
112
2. Go to Account Settings → API Access
113
3. Generate a new API token with appropriate permissions
114
4. Use the token in the authenticator configuration
115

116
### API Version
117

118
Webflow uses semantic versioning for their API:
119
- Current stable version: "1.0.0"
120
- The connector defaults to "1.0.0" if not specified
121
- Version must match Webflow's supported API versions
122

123
## Error Handling
124

125
Common authentication errors:
126

127
- **401 Unauthorized**: Invalid or expired API token
128
- **403 Forbidden**: Token lacks required permissions for the site
129
- **429 Too Many Requests**: Rate limiting (authenticator doesn't handle retry logic)
130

131
The authenticator itself doesn't handle these errors - they're returned by the API and should be handled at the stream or source level.
132

133
## Security Considerations
134

135
- API tokens should be treated as secrets and not logged or exposed
136
- Tokens have site-specific permissions in Webflow
137
- Consider rotating tokens periodically for security
138
- Use environment variables or secret management systems for token storage
139

140
## Integration with Airbyte CDK
141

142
The WebflowTokenAuthenticator integrates seamlessly with Airbyte's CDK:
143

144
```python
145
from airbyte_cdk.sources.streams.http import HttpStream
146
from source_webflow.auth import WebflowTokenAuthenticator
147

148
class MyWebflowStream(HttpStream):
149
    def __init__(self, authenticator: WebflowTokenAuthenticator, **kwargs):
150
        super().__init__(authenticator=authenticator, **kwargs)
151
    
152
    # The authenticator will automatically be used for all HTTP requests
153
    # made by this stream
154
```