Save the credentials of a pulled directory source
PUT /v1/directories/{dir}/source: Save the credentials of a pulled directory source.
PUT /
Checks the credentials with one read call to the source, then stores them sealed and schedules a sync now; the worker then polls every 5 minutes, backing off up to an hour after failures. bamboohr takes no pasted credentials: it connects only through POST /v1/directories/{dir}/source/oauth/start (Connect BambooHR), and a PUT answers directory_source_method_unavailable. rippling_hris: api_token. google_admin_sdk (Google Workspace) takes no pasted credentials either: it connects only through Connect Google (POST /v1/directories/{dir}/source/oauth/start), and a PUT answers directory_source_method_unavailable. workday: report_url (an https RaaS report URL on a workday.com or myworkday.com host, JSON format, with columns employee_id, email, first_name, last_name and optional title, department, manager_id, active), username and password of the integration system user. hibob: service_user_id, token. personio: client_id, client_secret. gusto: access_token, company_id (legacy: a pasted access token expires and is never refreshed; connect Gusto with POST /v1/directories/{dir}/source/oauth/start instead). sftp_csv: host, optional port (default 22), username, host_key_fingerprint (required; the server’s SHA256 host key fingerprint as ssh-keygen -l prints it; the first connection never trusts an unknown key), path (an absolute file path; the last segment may be a glob, and the newest matching file is read), and private_key (an OpenSSH or PEM Ed25519 or RSA key) unless a key pair was generated with POST /v1/directories/{dir}/source/ssh_key, whose private key is then used. The file is parsed and applied with the CSV import rules (10 MiB, 50,000 users). Only public addresses are reached. Optional sync_interval_minutes (5 to 1440) sets the poll interval. Refused or malformed credentials answer directory_source_credentials_invalid, an unreachable source directory_source_unavailable; nothing is stored then. A directory of another provider answers directory_source_mismatch.
- Scope
directories:write- Auth
- Secret key (
sk_…) - Since
- 1.0
Path parameters
Section titled “Path parameters”dirstring Required
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Request body
Section titled “Request body”
The source’s credentials (see the operation); never returned or logged.credentialsobject Required
Minutes between successful polls; default 5.sync_interval_minutesintegermin 5 · max 1440
Responses
Section titled “Responses”- 200 OK DirectorySource
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 404 Code: resource_not_found (also returned for other tenants’ IDs); a path no endpoint serves answers route_not_found. A browser GET or HEAD of an unknown path whose Accept ranks text/html above JSON gets an HTML 404 page instead, with the same status; every other client gets this JSON body. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
Errors share one shape; see the error code catalogue.
curl -X PUT \ "https://api.ohauthcat.com/v1/directories/dir_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/source" \ -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credentials": {}}'const response = await fetch("https://api.ohauthcat.com/v1/directories/dir_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/source", { method: "PUT", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "credentials": {} }),});const data = await response.json();import osimport requests
response = requests.put( "https://api.ohauthcat.com/v1/directories/dir_01J9Z3K5V7W8X9Y0Z1A2B3C4D5/source", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "credentials": {}, },)data = response.json(){ "object": "directory_source", "directory_id": "dir_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "kind": "bamboohr", "next_sync_at": "2026-01-15T09:30:00Z", "last_synced_at": "2026-01-15T09:30:00Z", "last_error": "saml_signature_invalid", "failures": 1, "sync_interval_minutes": 1, "last_result": {}, "last_skipped": [ { "external_id": "acme-123", "name": "Acme Corp", "reason": "no_id" } ]}