# Pulled directory sources

Some customers cannot push SCIM. For them a directory can be a **pulled source**: OhAuthCat reads the source on a schedule and applies the result with the same rules as a [CSV import](/idp-guides/csv/directory-sync/). Changes reach you as the usual [directory events](/directory-sync/events/).

| Provider           | Source                                   | Credentials (`PUT /v1/directories/{dir}/source`)                                                                                   | Setup guide                                                      |
| ------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `sftp_csv`         | A CSV file on the customer's SFTP server | `host`, optional `port` (22), `username`, `host_key_fingerprint`, `path`, and `private_key` unless a key pair was generated        | [SFTP (CSV)](/idp-guides/sftp-csv/directory-sync/)               |
| `workday`          | Workday Reports-as-a-Service, JSON       | `report_url`, `username`, `password` (an integration system user)                                                                  | [Workday](/idp-guides/workday/directory-sync/)                   |
| `hibob`            | HiBob people search                      | `service_user_id`, `token`                                                                                                         | [HiBob](/idp-guides/hibob/directory-sync/)                       |
| `personio`         | Personio employees                       | `client_id`, `client_secret`                                                                                                       | [Personio](/idp-guides/personio/directory-sync/)                 |
| `bamboohr`         | BambooHR employee directory              | None: connect from the setup portal with Connect BambooHR (OAuth); API keys are refused with `directory_source_method_unavailable` | [BambooHR](/idp-guides/bamboohr/directory-sync/)                 |
| `rippling_hris`    | Rippling                                 | `api_token`                                                                                                                        | [Rippling (HRIS)](/idp-guides/rippling-hris/directory-sync/)     |
| `google_admin_sdk` | Google Workspace                         | None: connect from the setup portal with Connect Google (OAuth)                                                                    | [Google Workspace](/idp-guides/google-admin-sdk/directory-sync/) |

Connect Google is the recommended Google Workspace source: it syncs people and groups, with group members, and works in every Workspace. Google can also push people to a SCIM directory (provider `google`) through its custom SCIM profiles beta; see [Google Workspace (SCIM, beta)](/idp-guides/google-workspace/directory-sync/). That route sends people only, never groups, skips people on secondary domains and works only in Workspaces Google admitted to the beta.

The hosted setup portal offers the same setup, so an organization's IT admin can connect the source without you handling their credentials.

## Creating the directory

Create the directory with `POST /v1/directories` and the source's `provider`, as for any directory. A pulled directory, and a `csv` directory, has no SCIM endpoint: the response has no `scim_base_url` and no `token`, and SCIM requests to it answer [`directory_source_mismatch`](/errors/directory_source_mismatch/). Its `state` is `awaiting_first_sync` until the first successful sync (or, for `csv`, the first import), then `active`.

## Saving credentials

Saving checks the credentials with one read from the source, then stores them sealed and schedules a sync right away. Credentials are never returned. Refused or malformed credentials answer [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/) and an unreachable source [`directory_source_unavailable`](/errors/directory_source_unavailable/); nothing is stored in either case. A directory of another provider answers [`directory_source_mismatch`](/errors/directory_source_mismatch/).

`GET /v1/directories/{dir}/source` returns the poll state: `next_sync_at`, `last_synced_at`, `last_error`, `failures`, `sync_interval_minutes` and the counts of the last successful poll.

## Connecting with OAuth (Gusto, BambooHR, Google)

Gusto, BambooHR and Google Workspace connect through OAuth instead of stored credentials: the setup portal's Connect button, or `POST /v1/directories/{dir}/source/oauth/start` from your server.

1. The answer's `authorization_url` is an OhAuthCat confirm page, not the provider. It names the organization and environment the directory will attach to, so the IT admin can see where their people will go before they approve anything. Send the IT admin's browser there within 30 minutes.
2. Only pressing **Continue** on that page, in the same browser, sends them on to the provider's consent screen. A flow that reaches the callback without that confirmation is refused with [`directory_source_oauth_confirm_required`](/errors/directory_source_oauth_confirm_required/) and nothing is connected. An unknown, expired or used link answers [`directory_source_oauth_state_invalid`](/errors/directory_source_oauth_state_invalid/).
3. For Google, the Workspace domain of the admin who approves must be a verified domain of the directory's organization. Otherwise the grant is refused with [`directory_source_oauth_domain_unverified`](/errors/directory_source_oauth_domain_unverified/) and nothing is stored. Have the organization verify its domain first, with a portal link for the `domain_verification` or `sso` [intent](/hosted-portal/intents/) or `POST /v1/organizations/{org}/domains`.
4. The browser returns to your `return_url` with `ohauthcat_oauth` set to `connected`, `choose_company` (Gusto, when the grant reaches several companies) or `error` with `error_code`, plus `directory_id`.

Never build the provider's consent URL yourself or skip the confirm page; the callback refuses any flow that did not pass it.

## Sync interval

Each source is read every 5 minutes by default. Set `sync_interval_minutes` (5 to 1440) with the credentials to read less often, for example once a day for a nightly HR export. To change only the interval later, send `PATCH /v1/directories/{dir}/source` with `{"sync_interval_minutes": 1440}`: the credentials, and a Gusto, BambooHR or Google OAuth connection, stay as they are. The route answers 404 until a source has been saved. After a failure the worker waits longer between tries, up to an hour, whatever the interval.

## Preview before the first sync

`POST /v1/directories/{dir}/source/preview` (or the portal's **Preview** button) reads the source once with the saved credentials and returns what a sync would add, update and remove, without changing anything. Use it to catch a wrong report, a filtered export or missing columns before people are deprovisioned. Unreadable data answers [`directory_csv_invalid`](/errors/directory_csv_invalid/).

## SFTP sources

- **Key pair.** `POST /v1/directories/{dir}/source/ssh_key` generates an Ed25519 key pair. The private key is sealed and never returned; the response has `public_key` (an OpenSSH `authorized_keys` line) and its `fingerprint`. Install the public key for the SFTP user, then save the credentials without `private_key`. Generating again replaces the pair; a source saved earlier keeps its key until its credentials are saved again. `GET` on the same route returns the current public key. Customers who prefer their own key send an Ed25519 or RSA (2048 bits or more) `private_key` instead. Password authentication is not supported.
- **Host key pinning.** `host_key_fingerprint` is required. It is the server's SHA256 fingerprint as `ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key.pub` prints it on the server, or as `ssh-keyscan <host> | ssh-keygen -lf -` prints it from elsewhere (check that value with the server's admin). An unknown key is never trusted on first use. A server whose key does not match answers [`directory_source_host_key_mismatch`](/errors/directory_source_host_key_mismatch/) and syncs stop until the new fingerprint is saved.
- **Path.** `path` is absolute. Its last segment may be a glob such as `/exports/users-*.csv`; the newest matching file is read. No match answers [`directory_source_file_not_found`](/errors/directory_source_file_not_found/).
- **File.** The CSV columns and limits are the CSV import's (10 MiB, 50,000 users). Each sync applies the whole file, so people missing from it are removed.
- **Network.** Only public addresses are reached, with a 15 second connect and 2 minute session limit.

## HRIS sources

- **Workday** reads a custom report published as a web service. The `report_url` must be https on a `workday.com` or `myworkday.com` host and return JSON, with columns `employee_id`, `email`, `first_name`, `last_name` and optional `title`, `department`, `manager_id`, `active`.
- **HiBob** uses an API service user with view access to the default employee fields.
- **Personio** uses API credentials with read access to employees; only the attributes the credential may read are shared.

Every HRIS sync reads the full list. Terminated or inactive people are deprovisioned, departments become groups, and rate-limit or server errors are retried with the source's `Retry-After`.
