Pulled directory sources
Directories that OhAuthCat reads on a schedule instead of receiving SCIM: a CSV file on an SFTP server, and the Workday, HiBob, Personio, BambooHR, Rippling and Google Workspace APIs. Covers credentials, host-key pinning, previews and the sync interval.
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. Changes reach you as the usual directory events.
| Provider | Source | Credentials (PUT /) |
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) |
workday |
Workday Reports-as-a-Service, JSON | report_url, username, password (an integration system user) |
Workday |
hibob |
HiBob people search | service_user_id, token |
HiBob |
personio |
Personio employees | client_id, client_secret |
Personio |
bamboohr |
BambooHR employee directory | None: connect from the setup portal with Connect BambooHR (OAuth); API keys are refused with directory_source_method_unavailable |
BambooHR |
rippling_hris |
Rippling | api_token |
Rippling (HRIS) |
google_admin_sdk |
Google Workspace | None: connect from the setup portal with Connect Google (OAuth) | Google Workspace |
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). 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
Section titled “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. Its state is awaiting_first_sync until the first successful sync (or, for csv, the first import), then active.
Saving credentials
Section titled “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 and an unreachable source directory_source_unavailable; nothing is stored in either case. A directory of another provider answers directory_source_mismatch.
GET / 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)
Section titled “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 / from your server.
- The answer’s
authorization_urlis 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. - 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_requiredand nothing is connected. An unknown, expired or used link answersdirectory_source_oauth_state_invalid. - 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_unverifiedand nothing is stored. Have the organization verify its domain first, with a portal link for thedomain_verificationorssointent orPOST /.v1/ organizations/ {org}/ domains - The browser returns to your
return_urlwithohauthcat_oauthset toconnected,choose_company(Gusto, when the grant reaches several companies) orerrorwitherror_code, plusdirectory_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
Section titled “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 / 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
Section titled “Preview before the first sync”POST / (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.
SFTP sources
Section titled “SFTP sources”- Key pair.
POST /generates an Ed25519 key pair. The private key is sealed and never returned; the response hasv1/ directories/ {dir}/ source/ ssh_key public_key(an OpenSSHauthorized_keysline) and itsfingerprint. Install the public key for the SFTP user, then save the credentials withoutprivate_key. Generating again replaces the pair; a source saved earlier keeps its key until its credentials are saved again.GETon the same route returns the current public key. Customers who prefer their own key send an Ed25519 or RSA (2048 bits or more)private_keyinstead. Password authentication is not supported. - Host key pinning.
host_key_fingerprintis required. It is the server’s SHA256 fingerprint asssh-keygen -l -f /prints it on the server, or asetc/ ssh/ ssh_host_ed25519_key. pub 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 answersdirectory_source_host_key_mismatchand syncs stop until the new fingerprint is saved. - Path.
pathis absolute. Its last segment may be a glob such as/exports/users-*.csv; the newest matching file is read. No match answersdirectory_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
Section titled “HRIS sources”- Workday reads a custom report published as a web service. The
report_urlmust be https on aworkday.comormyworkday.comhost and return JSON, with columnsemployee_id,email,first_name,last_nameand optionaltitle,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.