A connector reads one kind of system. Each source in your config uses one connector, and each connector produces records, episodes or both.
| Connector | Name | Records | Episodes | Credentials |
|---|---|---|---|---|
| CSV and JSON folder | csv |
Yes | No | None |
| Postgres | postgres |
Yes | No | Connection URL |
| Xero | xero |
Yes | No | App client ID and secret, refresh token |
| QuickBooks | quickbooks |
Yes | No | App client ID and secret, refresh token |
| HubSpot | hubspot |
Yes | No | Private app token |
| Salesforce | salesforce |
Yes | Yes | Connected app refresh token |
| Zendesk | zendesk |
Yes | Yes | Admin email and API token |
| Jira | jira |
Yes | Yes | Account email and API token |
| Linear | linear |
Yes | Yes | Personal API key |
| GitHub | github |
Yes | Yes | Fine-grained access token |
Records and episodes
Records are rows: an invoice, a deal, a ticket, an issue. Every connector produces them.
Episodes are ordered histories built from a system's audit trail: who changed what, when, and what happened next. Only systems that keep a change history can produce them. The SDK turns each connector's audit events into episodes and scrubs them like records. See Data formats.
Read-only access
Every connector only reads. Give each one the narrowest read-only credentials the system offers: a read-only database user, a private app with read scopes, a fine-grained token limited to the repositories you want to share. Each connector page lists the exact scopes.
Where credentials live
Credentials never go into datayield.config.json. When you run datayield connect, the SDK stores secret options, such as tokens, client secrets, refresh tokens and connection URLs, in ~/.datayield/credentials, readable only by your user. For CI, set an option to env:NAME and the SDK reads it from that environment variable at run time. See Configuration.
Credentials are used only on the machine that runs the SDK. The SDK calls each system directly from that machine. Source data and tokens are never sent to Datayield.
Errors
When a system rejects the credentials, the SDK stops with a message that names the system and what to fix: a wrong or expired token for a 401, a missing scope or permission for a 403. Rate limits and server errors are retried with backoff. See Troubleshooting.
Systems without a connector
Export the data to CSV, JSON or JSON Lines on a schedule and point the CSV connector at the folder. If your data lives in Postgres, the Postgres connector can read it directly with a query you write.