Skip to content
Dashboard
Theme
Theme

Save the credentials of a pulled directory source

PUT /v1/directories/{dir}/source: Save the credentials of a pulled directory source.

View Markdown

PUT /v1/directories/{dir}/source

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
  • dir string Required

  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • credentials object Required

    The source’s credentials (see the operation); never returned or logged.

  • sync_interval_minutes integer

    Minutes between successful polls; default 5.

    min 5 · max 1440

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": {}
}'
Response 200
{
"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"
}
]
}