0
# Authentication & Configuration
1

2
Authentication and configuration system for the HubSpot source connector, supporting multiple authentication methods and comprehensive synchronization options.
3

4
## Capabilities
5

6
### OAuth Authentication
7

8
OAuth 2.0 authentication flow for accessing HubSpot APIs with user-delegated permissions.
9

10
```yaml { .api }
11
credentials:
12
  credentials_title: "OAuth Credentials"
13
  client_id: string        # HubSpot application client ID
14
  client_secret: string    # HubSpot application client secret  
15
  refresh_token: string    # OAuth refresh token for automatic renewal
16
```
17

18
**Usage Example:**
19

20
```yaml
21
source:
22
  type: airbyte/source-hubspot
23
  config:
24
    credentials:
25
      credentials_title: "OAuth Credentials"
26
      client_id: "${HUBSPOT_CLIENT_ID}"
27
      client_secret: "${HUBSPOT_CLIENT_SECRET}"
28
      refresh_token: "${HUBSPOT_REFRESH_TOKEN}"
29
    start_date: "2023-01-01T00:00:00Z"
30
```
31

32
### Private App Authentication
33

34
Private App token authentication for server-to-server access with scoped permissions.
35

36
```yaml { .api }
37
credentials:
38
  credentials_title: "Private App Credentials"
39
  access_token: string     # HubSpot Private App access token
40
```
41

42
**Usage Example:**
43

44
```yaml
45
source:
46
  type: airbyte/source-hubspot
47
  config:
48
    credentials:
49
      credentials_title: "Private App Credentials"
50
      access_token: "${HUBSPOT_ACCESS_TOKEN}"
51
    start_date: "2023-01-01T00:00:00Z"
52
```
53

54
### Start Date Configuration
55

56
Configures the starting point for incremental data synchronization.
57

58
```yaml { .api }
59
start_date:
60
  type: string
61
  format: date-time
62
  pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
63
  default: "2006-06-01T00:00:00Z"
64
  description: "UTC datetime for incremental sync starting point"
65
```
66

67
**Usage Examples:**
68

69
```yaml
70
# Start from specific date
71
start_date: "2023-01-01T00:00:00Z"
72

73
# Start from beginning of current year
74
start_date: "2024-01-01T00:00:00Z"
75

76
# Default behavior (omit for default)
77
# start_date defaults to "2006-06-01T00:00:00Z"
78
```
79

80
### Experimental Streams
81

82
Controls access to experimental or beta data streams that may have unstable schemas.
83

84
```yaml { .api }
85
enable_experimental_streams:
86
  type: boolean
87
  default: false
88
  description: "Enable access to experimental data streams"
89
```
90

91
**Usage Example:**
92

93
```yaml
94
source:
95
  type: airbyte/source-hubspot
96
  config:
97
    credentials:
98
      credentials_title: "Private App Credentials"
99
      access_token: "${HUBSPOT_ACCESS_TOKEN}"
100
    enable_experimental_streams: true
101
```
102

103
### Concurrency Configuration
104

105
Controls the number of concurrent workers for parallel data processing.
106

107
```yaml { .api }
108
num_worker:
109
  type: integer
110
  minimum: 1
111
  maximum: 40
112
  default: 3
113
  description: "Number of concurrent workers for data extraction"
114
```
115

116
**Usage Examples:**
117

118
```yaml
119
# High throughput configuration
120
num_worker: 10
121

122
# Conservative configuration for rate limit compliance
123
num_worker: 1
124

125
# Default behavior (omit for default)
126
# num_worker defaults to 3
127
```
128

129
### Incremental Sync Configuration
130

131
Controls the lookback window for incremental synchronization to handle late-arriving data.
132

133
```yaml { .api }
134
lookback_window:
135
  type: integer
136
  minimum: 0
137
  default: 0
138
  description: "Number of days to look back from cursor position for incremental sync"
139
```
140

141
**Usage Examples:**
142

143
```yaml
144
# Handle late-arriving data with 1-day lookback
145
lookback_window: 1
146

147
# Handle significant delays with 7-day lookback
148
lookback_window: 7
149

150
# Default behavior (no lookback)
151
# lookback_window defaults to 0
152
```
153

154
### Complete Configuration Schema
155

156
```yaml { .api }
157
SourceHubSpotConfig:
158
  type: object
159
  required:
160
    - credentials
161
  properties:
162
    credentials:
163
      oneOf:
164
        - $ref: "#/definitions/OAuthCredentials"
165
        - $ref: "#/definitions/PrivateAppCredentials"
166
    start_date:
167
      type: string
168
      format: date-time
169
      default: "2006-06-01T00:00:00Z"
170
    enable_experimental_streams:
171
      type: boolean
172
      default: false
173
    num_worker:
174
      type: integer
175
      minimum: 1
176
      maximum: 40
177
      default: 3
178
    lookback_window:
179
      type: integer
180
      minimum: 0
181
      default: 0
182

183
OAuthCredentials:
184
  type: object
185
  required:
186
    - credentials_title
187
    - client_id
188
    - client_secret
189
    - refresh_token
190
  properties:
191
    credentials_title:
192
      type: string
193
      const: "OAuth Credentials"
194
    client_id:
195
      type: string
196
      description: "HubSpot application client ID"
197
    client_secret:
198
      type: string
199
      description: "HubSpot application client secret"
200
    refresh_token:
201
      type: string
202
      description: "OAuth refresh token for automatic renewal"
203

204
PrivateAppCredentials:
205
  type: object
206
  required:
207
    - credentials_title
208
    - access_token
209
  properties:
210
    credentials_title:
211
      type: string
212
      const: "Private App Credentials"
213
    access_token:
214
      type: string
215
      description: "HubSpot Private App access token"
216
```
217

218
### Authentication Flow Details
219

220
**OAuth Flow:**
221
1. Application redirects user to HubSpot OAuth authorization URL
222
2. User grants permissions and is redirected back with authorization code
223
3. Application exchanges code for access and refresh tokens
224
4. Connector uses refresh token to obtain fresh access tokens automatically
225

226
**Private App Flow:**
227
1. Create Private App in HubSpot developer account
228
2. Configure required scopes for data access
229
3. Generate access token from Private App settings
230
4. Use access token directly in connector configuration
231

232
### Required Scopes
233

234
The connector requires the following HubSpot scopes depending on enabled streams:
235

236
**Core CRM Scopes:**
237
- `crm.objects.contacts.read`
238
- `crm.objects.companies.read` 
239
- `crm.objects.deals.read`
240
- `tickets`
241

242
**Marketing Scopes:**
243
- `content`
244
- `forms`
245
- `email`
246

247
**Engagement Scopes:**
248
- `engagements`
249

250
**Additional Scopes:**
251
- `settings.users.read` (for owners)
252
- `crm.schemas.custom.read` (for custom objects)