> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkOS enterprise health

> Resources, examples, configuration and evidence for WorkOS enterprise health.

Use the `@bijectionhq/connectors/workos-enterprise` entrypoint to declare WorkOS enterprise health resources.

## Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. [Source build and package availability](https://docs.bijection.com/client/sdk-distribution.md).

## Resources and modes

| Resource | Mode | Description |
| - | - | - |
| Reviewed connection, directory and certificate health | `observations` | Current provider observations |

Declare a resource in application code, then bind deployment-specific settings and credentials. See [typed resources](https://docs.bijection.com/integrations/resources.md), [connections](https://docs.bijection.com/integrations/connections.md) and [source inspection](https://docs.bijection.com/integrations/cli.md).

## Reviewed connection, directory and certificate health

### observations: Current provider observations

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { workosEnterprise } from "@bijectionhq/connectors/workos-enterprise";
export const health = workosEnterprise.health.observations({
  organization: "org_example",
  connection: "conn_example",
  directory: "directory_example",
});
```

> [accordion] Inferred record types
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "id": string;
>   "organization": string;
>   "connectionType": string;
>   "connectionState": string;
>   "directory": string | null;
>   "directoryState": string | null;
>   "certificateState": "unavailable" | "observed" | "notApplicable";
>   "certificates": { id: string; notBefore: number | null; notAfter: number | null; }[];
>   "ssoEnforced": null;
> }
> ```

#### Configuration: standard

Case: `workos-enterprise/health/observations/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.

> [accordion] Complete configuration contract
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {},
>     "defaults": {},
>     "connector": "workos-enterprise",
>     "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 | Deletion detection unsupported |
| Resume | No continuation |
| Gap | Not applicable |
| Retention | Unspecified |
| Coverage | Individual record evidence |
| Consistency | Independent observations |
| Atomicity | One record |
| History | Current record observations |
| Bound: http\_response\_bytes | 524288 |

> [accordion] Complete native profile
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "movement": {
>     "exchanges": {
>       "certificates": {
>         "200": {
>           "placement": "retained_bytes",
>           "interpretation": "json",
>           "projectsBeforeRetention": false,
>           "retainedBodyLimitBytes": "524288",
>           "fileLimitBytes": null
>         },
>         "400": {
>           "placement": "retained_bytes",
>           "interpretation": "opaque",
>           "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
>         }
>       },
>       "connection": {
>         "200": {
>           "placement": "retained_bytes",
>           "interpretation": "json",
>           "projectsBeforeRetention": false,
>           "retainedBodyLimitBytes": "524288",
>           "fileLimitBytes": null
>         },
>         "400": {
>           "placement": "retained_bytes",
>           "interpretation": "opaque",
>           "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
>         }
>       },
>       "directory": {
>         "200": {
>           "placement": "retained_bytes",
>           "interpretation": "json",
>           "projectsBeforeRetention": false,
>           "retainedBodyLimitBytes": "524288",
>           "fileLimitBytes": null
>         },
>         "400": {
>           "placement": "retained_bytes",
>           "interpretation": "opaque",
>           "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
>         }
>       }
>     },
>     "nativeInputLimitBytes": null,
>     "steps": [
>       {
>         "id": "acquire.1",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "exchange certificates",
>           "limitBytes": null
>         }
>       },
>       {
>         "id": "acquire.2",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "exchange connection",
>           "limitBytes": null
>         }
>       },
>       {
>         "id": "acquire.3",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "exchange directory",
>           "limitBytes": null
>         }
>       },
>       {
>         "id": "acquire.4",
>         "inputs": [],
>         "action": {
>           "operation": "acquire",
>           "subject": "listener changes",
>           "limitBytes": null
>         }
>       },
>       {
>         "id": "retain.1",
>         "inputs": [
>           "acquire.1",
>           "acquire.2",
>           "acquire.3",
>           "acquire.4"
>         ],
>         "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": "unsupported",
>   "resume": "none",
>   "retentionMs": null,
>   "gap": "not_applicable",
>   "limits": {
>     "http_response_bytes": "524288"
>   },
>   "restrictions": [],
>   "commands": {}
> }
> ```

> [accordion] Commands, occurrences and artifacts
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "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 or real-provider qualification covers this case. Package fixtures verify interpretation only. | Execution result unavailable |
| identity-account | \{"kind":"connection"} | No retained native or real-provider qualification covers this case. Package fixtures verify interpretation only. | 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.

## Provider guidance

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import {workosEnterprise} from '@bijectionhq/connectors/workos-enterprise';
export const health=workosEnterprise.health.observations({
  organization:'org_example',connection:'conn_example',directory:'directory_example',
});
```

Bind the resulting source through the normal native connection owner to
`https://api.workos.com` and a `workos` credential. The reviewed organization and
connection IDs are fixed in code. Directory selection is optional and exact.
Read the source row under the same organization authorization as its setup.

Native acquisition reads the organization, selected connection, selected directory,
and the connection's IdP signing certificate list. Certificate material is discarded;
only IDs and validity dates are published. The certificate API is feature flagged:
403/404 is unavailable evidence, never an empty certificate list. Active connection
state proves neither an SSO ceremony nor enforcement of SSO for all sign-ins.
The API does not expose an enforcement fact here, so `ssoEnforced` stays null.

Use `defineWorkosEnterpriseHealth` with a fixed internal query of this source row,
its **record** evidence and source inspection subject. The factory produces separate
connection and certificate proofs. It never substitutes acquisition completion time
for native observation time, never treats directory `active`/`linked` as complete
membership coverage, and never claims a consumed event cursor was applied.
Use the original directory source's evidence for the separate directory proof.

Ordered WorkOS events trigger refreshes; periodic reads bound missed notifications.
Refresh/reconnect/rebaseline go through the existing source and connection controls.
Only successful native rereads establish new readiness evidence. Unknown states and
expired record observations fail closed. No provider action is repeated by a proof.

References: [connections](https://workos.com/docs/reference/sso/connection),
[certificates](https://workos.com/docs/reference/sso/saml-idp-signing-certificate),
[directories](https://workos.com/docs/reference/directory-sync/directory).

## Install readiness proofs

Add an `enterpriseProviderHealth` resource parented by `organization` with `read`
permission, and grant its readers explicitly in the application's roles. Keep
provider observations source-owned:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// workos.ts — reviewed provider selection; no API key in application code.
import { workosEnterprise } from '@bijectionhq/connectors/workos-enterprise';
import { v } from 'bijection/values';
export const health = workosEnterprise.health.observations({
  organization: 'org_example', connection: 'conn_example',
  directory: 'directory_example',
}).withScope({organizationId: v.id('organizations')});

// schema.ts — alongside the existing enterprise starter tables.
workosHealth: defineTable(health.row).sync(health, {
  read: {population: 'observed', stale: 'allowed'},
}).index('by_organization', ['organizationId']).access(
  access.resources.enterpriseProviderHealth, {
    parent: {field: 'organizationId', index: 'by_organization'},
    read: {permission: 'read', fields: [
      'id', 'organizationId', 'organization', 'connectionType', 'connectionState',
      'directory', 'directoryState', 'certificateState', 'certificates', 'ssoEnforced',
    ]},
  }),
```

The diagnostic table permits stale reads so status can explain them. The proof
owner independently requires current **native record** evidence. Bind the scoped
resource with the normal deployment `bind(resources.workos.health, {setup:{},
credential:workosEnterprise.credential('WORKOS'),scope:{organizationId}})`.

Install the concrete source reader. Its configuration query returns
`{configuration:{issuer,clientId,providerOrganization},selection:{connection,directory}}`
from the local organization's reviewed settings. Share the reviewed selection
with `workos.ts`; callers never submit it. Reads retain the source table's ordinary
authorization and the fixed owner index.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// workosHealthInput.ts
import {defineWorkosEnterpriseHealthReader} from 'bijection/server';
import {internal} from './_generated/api';
export const read=defineWorkosEnterpriseHealthReader({
  table:'workosHealth', index:'by_organization', ownerField:'organizationId',
  configuration:internal.enterpriseProofs.workosConfiguration,
  anchor:internal.workosHealthInput.read,
});
```

The reader strips local metadata and obtains evidence from
`ctx.sources.evidence({sourceId:row._sourceId},{record:row._id})`. An absent row
returns unavailable input. A different owner or missing native source provenance
refuses. It creates an inspection subject under the same fixed read owner.
Custom fixed readers can supply additional directory evidence under
`workosEnterpriseHealthObservation`; no public endpoint accepts acquired facts.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// workosHealth.ts — fixed installed read owner, ordinary internal functions.
import {defineWorkosEnterpriseHealth} from 'bijection/server';
import {internal} from './_generated/api';
export const {
  status, connection, certificate, directory, policy,
  connectionProof, certificateProof, directoryProof, policyProof,
} = defineWorkosEnterpriseHealth({
  module:'workosHealth',read:internal.workosHealthInput.read,maximumAgeMs:60_000,
}).functions;
```

Register the factory's `inspectionOwner` in the application's existing inspection owners to resolve its source references.

Add `workosConnection:internal.workosHealth.connectionProof` and, for a SAML
configuration requiring certificate readiness,
`workosCertificate:internal.workosHealth.certificateProof` to the existing
`defineEnterpriseSetup({proofs:...})`. The enterprise starter doctor reports these
named installed proofs and their actual outcomes. Keep the native SSO canary:
connection and certificate proofs establish different facts.

The optional `directoryEvidence` input names its exact reviewed `directory`,
inspection `source`, and the original membership source's native `evidence`.
`directoryProof` needs complete population coverage, freshness, a provider
checkpoint and an applied publication ID independently. The health row cannot
supply these. WorkOS live paginated directory observations currently offer
positive records without snapshot coverage; they cannot pass a complete
population proof. Use per-record freshness for authorization and keep full
coverage unavailable until the source actually proves it.

`policyProof` remains unavailable: these read APIs supply no authoritative
all-methods SSO enforcement fact. Install a separate fixed policy owner if the
provider makes that evidence available. Do not activate a policy-dependent setup
by inferring enforcement from a successful SSO login.

## 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](https://github.com/bijectionhq/bijection/blob/main/npm-packages/connectors/src/connectors/workos-enterprise/README.md), [native analysis](https://github.com/bijectionhq/bijection/blob/main/npm-packages/connectors/contract-analysis.json) and [check receipts](https://github.com/bijectionhq/bijection/blob/main/npm-packages/connectors/evidence.json).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.