WorkOS Directory Sync

Use the @bijectionhq/connectors/workos-directory entrypoint to declare WorkOS Directory Sync resources.

Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. Source build and package availability.

Resources and modes

Resource	Mode	Description
Directory users	`enumeration`	Users with ordered event hints and reconciliation
Directory groups	`enumeration`	Groups with ordered event hints and reconciliation
Active group members	`enumeration`	Current group-scoped user observations

Declare a resource in application code, then bind deployment-specific settings and credentials. See typed resources, connections and source inspection.

Directory users

enumeration: Users with ordered event hints and reconciliation

The following example matches configuration standard.

import { workosDirectory } from "@bijectionhq/connectors/workos-directory";
export const people = workosDirectory.users.enumeration({
  directory: "directory_example",
  organization: "org_example",
});

Inferred record types

{
  "id": string;
  "directory": string;
  "organization": string;
  "idpId": string | null;
  "email": string | null;
  "name": string | null;
  "group": string | null;
}

Configuration: standard

Case: workos-directory/users/enumeration/standard. Connection and resource configuration are declared by this exact case. Credential kind: workos. Keep credential material in the private credential inventory. Inspect the complete configuration contract below for settings and conditional requirements.

Complete configuration contract

{
  "setup": [],
  "resource": {
    "access": {},
    "defaults": {},
    "connector": "workos-directory",
    "collections": [
      "records"
    ],
    "credential_kind": "workos",
    "connection_fields": [],
    "address": {
      "kind": "fixed",
      "url": "https://api.workos.com"
    }
  },
  "connection_setup": {
    "type": "object",
    "value": {}
  },
  "execution": null
}

Native admission analysis is available for this exact declaration. Collection: records

Contract	Meaning
Initial	Enumeration of observed records
Changes	Repeated observations of current records
Deletions	Explicit deletion evidence
Resume	Opaque cursor
Gap	Explicit repair required after a gap
Retention	Unspecified
Coverage	Individual record evidence
Consistency	Independent observations
Atomicity	One record
History	Current record observations
Bound: http_response_bytes	524288

Complete native profile

{
  "movement": {
    "exchanges": {
      "record": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "404": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "429": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      },
      "records": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "429": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      }
    },
    "nativeInputLimitBytes": null,
    "steps": [
      {
        "id": "acquire.1",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange record",
          "limitBytes": null
        }
      },
      {
        "id": "acquire.2",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange records",
          "limitBytes": null
        }
      },
      {
        "id": "acquire.3",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "listener changes",
          "limitBytes": null
        }
      },
      {
        "id": "retain.1",
        "inputs": [
          "acquire.1",
          "acquire.2",
          "acquire.3"
        ],
        "action": {
          "operation": "retain",
          "subject": "acquisition evidence",
          "reason": "recovery",
          "release": "acquisition_custody"
        }
      },
      {
        "id": "interpret.1",
        "inputs": [
          "retain.1"
        ],
        "action": {
          "operation": "interpret",
          "subject": "acquired input",
          "produces": "records"
        }
      },
      {
        "id": "materialize.1",
        "inputs": [
          "interpret.1"
        ],
        "action": {
          "operation": "materialize",
          "subject": "source rows",
          "reason": "serving",
          "release": "replacement"
        }
      },
      {
        "id": "publish.1",
        "inputs": [
          "materialize.1"
        ],
        "action": {
          "operation": "publish",
          "subject": "source rows",
          "visibility": "with_acquisition"
        }
      }
    ]
  },
  "initial": "enumeration",
  "changes": "observations",
  "deletions": "explicit_events",
  "resume": "opaque_cursor",
  "retentionMs": null,
  "gap": "explicit_repair",
  "limits": {
    "http_response_bytes": "524288"
  },
  "restrictions": [],
  "commands": {}
}

Commands, occurrences and artifacts

{
  "records": {
    "records": {
      "protocol": "record_observation",
      "coverage": "records",
      "consistency": "observations",
      "atomicity": "record",
      "history": "observations",
      "snapshotMaxRows": null
    }
  },
  "commands": {},
  "occurrences": null,
  "artifacts": {
    "raw_archive": false,
    "files": {}
  }
}

Recorded checks

Requirement	Scope	Evidence	Result
page-publication-recovery	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-empty-page-advances	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-repeat-refused	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
identity-account	{“kind”:“connection”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable

Verification scope

Evidence	Outcome	Applicability
packageFixtures	Not run	No applicable receipt
nativeContracts	Not run	No applicable receipt
deployedProvider	Not run	No applicable receipt
distributedPackage	Not run	No applicable receipt

Each evidence category has independent scope. A matching recorded pass applies only to its exact artifacts and configuration. Installed connections report their own identity, authority and current status.

Directory groups

enumeration: Groups with ordered event hints and reconciliation

The following example matches configuration standard.

import { workosDirectory } from "@bijectionhq/connectors/workos-directory";
export const groups = workosDirectory.groups.enumeration({
  directory: "directory_example",
  organization: "org_example",
});

Inferred record types

{
  "id": string;
  "directory": string;
  "organization": string;
  "idpId": string | null;
  "email": string | null;
  "name": string | null;
  "group": string | null;
}

Configuration: standard

Case: workos-directory/groups/enumeration/standard. Connection and resource configuration are declared by this exact case. Credential kind: workos. Keep credential material in the private credential inventory. Inspect the complete configuration contract below for settings and conditional requirements.

Complete configuration contract

{
  "setup": [],
  "resource": {
    "access": {},
    "defaults": {},
    "connector": "workos-directory",
    "collections": [
      "records"
    ],
    "credential_kind": "workos",
    "connection_fields": [],
    "address": {
      "kind": "fixed",
      "url": "https://api.workos.com"
    }
  },
  "connection_setup": {
    "type": "object",
    "value": {}
  },
  "execution": null
}

Native admission analysis is available for this exact declaration. Collection: records

Contract	Meaning
Initial	Enumeration of observed records
Changes	Repeated observations of current records
Deletions	Reconciliation
Resume	Opaque cursor
Gap	Explicit repair required after a gap
Retention	Unspecified
Coverage	Individual record evidence
Consistency	Independent observations
Atomicity	One record
History	Current record observations
Bound: http_response_bytes	524288

Complete native profile

{
  "movement": {
    "exchanges": {
      "record": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "404": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "429": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      },
      "records": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "429": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      }
    },
    "nativeInputLimitBytes": null,
    "steps": [
      {
        "id": "acquire.1",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange record",
          "limitBytes": null
        }
      },
      {
        "id": "acquire.2",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange records",
          "limitBytes": null
        }
      },
      {
        "id": "acquire.3",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "listener changes",
          "limitBytes": null
        }
      },
      {
        "id": "retain.1",
        "inputs": [
          "acquire.1",
          "acquire.2",
          "acquire.3"
        ],
        "action": {
          "operation": "retain",
          "subject": "acquisition evidence",
          "reason": "recovery",
          "release": "acquisition_custody"
        }
      },
      {
        "id": "interpret.1",
        "inputs": [
          "retain.1"
        ],
        "action": {
          "operation": "interpret",
          "subject": "acquired input",
          "produces": "records"
        }
      },
      {
        "id": "materialize.1",
        "inputs": [
          "interpret.1"
        ],
        "action": {
          "operation": "materialize",
          "subject": "source rows",
          "reason": "serving",
          "release": "replacement"
        }
      },
      {
        "id": "publish.1",
        "inputs": [
          "materialize.1"
        ],
        "action": {
          "operation": "publish",
          "subject": "source rows",
          "visibility": "with_acquisition"
        }
      }
    ]
  },
  "initial": "enumeration",
  "changes": "observations",
  "deletions": "reconciliation",
  "resume": "opaque_cursor",
  "retentionMs": null,
  "gap": "explicit_repair",
  "limits": {
    "http_response_bytes": "524288"
  },
  "restrictions": [],
  "commands": {}
}

Commands, occurrences and artifacts

{
  "records": {
    "records": {
      "protocol": "record_observation",
      "coverage": "records",
      "consistency": "observations",
      "atomicity": "record",
      "history": "observations",
      "snapshotMaxRows": null
    }
  },
  "commands": {},
  "occurrences": null,
  "artifacts": {
    "raw_archive": false,
    "files": {}
  }
}

Recorded checks

Requirement	Scope	Evidence	Result
page-publication-recovery	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-empty-page-advances	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-repeat-refused	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
identity-account	{“kind”:“connection”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable

Verification scope

Evidence	Outcome	Applicability
packageFixtures	Not run	No applicable receipt
nativeContracts	Not run	No applicable receipt
deployedProvider	Not run	No applicable receipt
distributedPackage	Not run	No applicable receipt

Active group members

enumeration: Current group-scoped user observations

The following example matches configuration standard.

import { workosDirectory } from "@bijectionhq/connectors/workos-directory";
export const members = workosDirectory.members.enumeration({
  directory: "directory_example",
  organization: "org_example",
  group: "directory_group_example",
});

Inferred record types

{
  "id": string;
  "directory": string;
  "organization": string;
  "idpId": string | null;
  "email": string | null;
  "name": string | null;
  "group": string | null;
}

Configuration: standard

Case: workos-directory/members/enumeration/standard. Connection and resource configuration are declared by this exact case. Credential kind: workos. Keep credential material in the private credential inventory. Inspect the complete configuration contract below for settings and conditional requirements.

Complete configuration contract

{
  "setup": [],
  "resource": {
    "access": {},
    "defaults": {},
    "connector": "workos-directory",
    "collections": [
      "records"
    ],
    "credential_kind": "workos",
    "connection_fields": [],
    "address": {
      "kind": "fixed",
      "url": "https://api.workos.com"
    }
  },
  "connection_setup": {
    "type": "object",
    "value": {}
  },
  "execution": null
}

Native admission analysis is available for this exact declaration. Collection: records

Contract	Meaning
Initial	Enumeration of observed records
Changes	Repeated observations of current records
Deletions	Explicit deletion evidence
Resume	Opaque cursor
Gap	Explicit repair required after a gap
Retention	Unspecified
Coverage	Individual record evidence
Consistency	Independent observations
Atomicity	One record
History	Current record observations
Bound: http_response_bytes	524288

Complete native profile

{
  "movement": {
    "exchanges": {
      "records": {
        "200": {
          "placement": "retained_bytes",
          "interpretation": "json",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "401": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "403": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "429": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        },
        "503": {
          "placement": "retained_bytes",
          "interpretation": "opaque",
          "projectsBeforeRetention": false,
          "retainedBodyLimitBytes": "524288",
          "fileLimitBytes": null
        }
      }
    },
    "nativeInputLimitBytes": null,
    "steps": [
      {
        "id": "acquire.1",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "exchange records",
          "limitBytes": null
        }
      },
      {
        "id": "acquire.2",
        "inputs": [],
        "action": {
          "operation": "acquire",
          "subject": "listener changes",
          "limitBytes": null
        }
      },
      {
        "id": "retain.1",
        "inputs": [
          "acquire.1",
          "acquire.2"
        ],
        "action": {
          "operation": "retain",
          "subject": "acquisition evidence",
          "reason": "recovery",
          "release": "acquisition_custody"
        }
      },
      {
        "id": "interpret.1",
        "inputs": [
          "retain.1"
        ],
        "action": {
          "operation": "interpret",
          "subject": "acquired input",
          "produces": "records"
        }
      },
      {
        "id": "materialize.1",
        "inputs": [
          "interpret.1"
        ],
        "action": {
          "operation": "materialize",
          "subject": "source rows",
          "reason": "serving",
          "release": "replacement"
        }
      },
      {
        "id": "publish.1",
        "inputs": [
          "materialize.1"
        ],
        "action": {
          "operation": "publish",
          "subject": "source rows",
          "visibility": "with_acquisition"
        }
      }
    ]
  },
  "initial": "enumeration",
  "changes": "observations",
  "deletions": "explicit_events",
  "resume": "opaque_cursor",
  "retentionMs": null,
  "gap": "explicit_repair",
  "limits": {
    "http_response_bytes": "524288"
  },
  "restrictions": [],
  "commands": {}
}

Commands, occurrences and artifacts

{
  "records": {
    "records": {
      "protocol": "record_observation",
      "coverage": "records",
      "consistency": "observations",
      "atomicity": "record",
      "history": "observations",
      "snapshotMaxRows": null
    }
  },
  "commands": {},
  "occurrences": null,
  "artifacts": {
    "raw_archive": false,
    "files": {}
  }
}

Recorded checks

Requirement	Scope	Evidence	Result
page-publication-recovery	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-empty-page-advances	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
stated-cursor-repeat-refused	{“kind”:“collection”,“name”:“records”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable
identity-account	{“kind”:“connection”}	No retained native provider check covers this WorkOS case. Source tests do not establish deployed directory behavior.	Execution result unavailable

Verification scope

Evidence	Outcome	Applicability
packageFixtures	Not run	No applicable receipt
nativeContracts	Not run	No applicable receipt
deployedProvider	Not run	No applicable receipt
distributedPackage	Not run	No applicable receipt

Provider guidance

These resources acquire reviewed directory observations through the existing native source, credential, listener and publication owners. They grant no roles, link no identities by email and perform no application provisioning side effects.

import { workosDirectory } from "@bijectionhq/connectors/workos-directory";

export const people = workosDirectory.users.enumeration({
  directory: "directory_example",
  organization: "org_example",
  every: { minutes: 15 },
  reconcileEvery: { hours: 1 },
  webhooks: true,
});
export const credential = workosDirectory.credential("WORKOS_DIRECTORY");

Install a native workos bearer credential containing a WorkOS API key. Bind the resource and credential using the ordinary deployment resource bindings. The fixed API origin is https://api.workos.com; secrets remain in native transport custody. Identity admission reads the selected directory and requires its exact directory ID, organization ID and active state. WorkOS provides no read-only API-key environment identity, so this proves the selected directory; it does not infer an environment from a credential label. users.enumeration and groups.enumeration use immutable provider IDs, enumeration and point reconciliation. An admitted 404 or explicitly inactive user withdraws the applicable observation. Authentication failures, outages, malformed pagination and unknown user states establish no empty population. Incomplete pages never claim completion. Native source freshness and the application’s participation policy determine how long earlier observations remain usable during an outage. members.enumeration({directory,organization,group}) acquires positive group-scoped user observations. The group must belong to the reviewed directory. WorkOS has no point membership read or snapshot guarantee for its live pages, so coverage remains none. A missing member’s earlier observation retains its original time and must expire under an explicit per-record source freshness requirement. Finishing a pass cannot renew it or prove deletion. Do not project these observations into unbounded durable grants. The deprecated user.groups field is never read. Each resource consumes the ordered Events API with a retained native after cursor and its documented 90-day retention. Events trigger source acquisition; late or replayed event payloads never overwrite current directory records. Periodic reconciliation remains independent of event delivery. An expired or refused cursor requires source repair and enumeration; it never silently skips an interval. Optional webhooks are additional signed refresh hints using exact raw-body HMAC verification, millisecond timestamps and a five-minute tolerance. Install the channel’s signing credential through the native listener owner. Inspect the existing source and listener owners for transport progress and native publication/coverage. The consumed provider cursor and applied access publication are separate observations; neither implies the other is current. Use the native source’s publication revision and coverage when projecting directory observations into participation. Keep that projection under its existing exclusive provisioning writer, and declare an access freshness bound. Removing this source removes its contribution; it does not delete a person or their independently granted authority. The package scenarios explicitly report missing provider qualification. The colocated source tests establish parsing and declaration behavior only. Live qualification remains opt-in. Provider contracts: Directory users, Directory groups, Events API.

Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

Source and evidence

Canonical connector source, native analysis and check receipts. Connector artifact: 455b2e3ba5a436b66a8f4c3fb2b05a442c4711673952d2f858e9da4ebdc097d6. The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.

Get Started

Use-case atlas

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

WorkOS Directory Sync

Availability

Resources and modes

Directory users

enumeration: Users with ordered event hints and reconciliation

Configuration: standard

Directory groups

enumeration: Groups with ordered event hints and reconciliation

Configuration: standard

Active group members

enumeration: Current group-scoped user observations

Configuration: standard

Provider guidance

Provider references

Source and evidence

​Availability

​Resources and modes

​Directory users

​enumeration: Users with ordered event hints and reconciliation

​Configuration: standard

​Directory groups

​enumeration: Groups with ordered event hints and reconciliation

​Configuration: standard

​Active group members

​enumeration: Current group-scoped user observations

​Configuration: standard

​Provider guidance

​Provider references

​Source and evidence

Availability

Resources and modes

Directory users

enumeration: Users with ordered event hints and reconciliation

Configuration: standard

Directory groups

enumeration: Groups with ordered event hints and reconciliation

Configuration: standard

Active group members

enumeration: Current group-scoped user observations

Configuration: standard

Provider guidance

Provider references

Source and evidence