# API schemas

<!-- Generated by scripts/generate.ts. Do not edit. -->

<!-- Source: core commit `f70874a3916ad5b24a8619246cbae6cc8bc24d27`. -->

API version **1.0.0**.

## Accepted

No description.

| Property   | Required | Type and constraints    | Description |
| ---------- | -------- | ----------------------- | ----------- |
| `accepted` | Yes      | boolean (`const: true`) | —           |

## AndroidAppLink

No description.

| Property       | Required | Type and constraints                                                                                       | Description                                                      |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `package_name` | Yes      | string (`minLength: 3`; `maxLength: 255`; `pattern: "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$"`) | The application ID (package name).                               |
| `apk_key_hash` | Yes      | string (`pattern: "^[A-Za-z0-9_-]{43}$"`)                                                                  | Base64url (no padding) SHA-256 of the app's signing certificate. |

## ApiKey

No description.

| Property          | Required | Type and constraints                                 | Description                                                                                                                                                                                                                                                |
| ----------------- | -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Yes      | [ApiKeyId](/reference/schemas/#apikeyid)             | —                                                                                                                                                                                                                                                          |
| `object`          | Yes      | string (`const: "api_key"`)                          | —                                                                                                                                                                                                                                                          |
| `name`            | No       | string                                               | —                                                                                                                                                                                                                                                          |
| `type`            | Yes      | string (`enum: ["secret","publishable"]`)            | —                                                                                                                                                                                                                                                          |
| `prefix`          | Yes      | string                                               | e.g. sk_test_abcd (never the full secret key).                                                                                                                                                                                                             |
| `publishable_key` | No       | string (`pattern: "^pk_"`)                           | The full publishable key (browser-safe; it is the client_id of authorize URLs). Set on publishable keys only, never on secret keys, which are shown once at creation. Absent on publishable keys created before it was stored; roll such a key to get one. |
| `revoked_at`      | No       | string or null (`format: "date-time"`)               | Set on the revoke response. Revoked keys drop out of every key list.                                                                                                                                                                                       |
| `environment`     | No       | [EnvironmentId](/reference/schemas/#environmentid)   | The key's environment (set in account-wide listings).                                                                                                                                                                                                      |
| `scopes`          | Yes      | Array of string                                      | —                                                                                                                                                                                                                                                          |
| `ip_allow_list`   | No       | Array of string                                      | —                                                                                                                                                                                                                                                          |
| `expires_at`      | No       | string or null (`format: "date-time"`)               | —                                                                                                                                                                                                                                                          |
| `last_used_at`    | No       | string or null (`format: "date-time"`)               | —                                                                                                                                                                                                                                                          |
| `created_at`      | No       | [Timestamp](/reference/schemas/#timestamp)           | —                                                                                                                                                                                                                                                          |
| `organization`    | No       | [OrganizationId](/reference/schemas/#organizationid) | Set on an organization-scoped key.                                                                                                                                                                                                                         |

## ApiKeyExtraSecret

No description.

| Property       | Required | Type and constraints                   | Description |
| -------------- | -------- | -------------------------------------- | ----------- |
| `id`           | Yes      | string                                 | —           |
| `object`       | Yes      | string (`const: "api_key_secret"`)     | —           |
| `prefix`       | Yes      | string                                 | —           |
| `last_used_at` | No       | string or null (`format: "date-time"`) | —           |
| `revoked_at`   | No       | string or null (`format: "date-time"`) | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)         | —           |

## ApiKeyExtraSecretCreated

No description.

| Property | Required | Type and constraints               | Description                  |
| -------- | -------- | ---------------------------------- | ---------------------------- |
| `id`     | Yes      | string                             | —                            |
| `object` | Yes      | string (`const: "api_key_secret"`) | —                            |
| `prefix` | Yes      | string                             | —                            |
| `secret` | Yes      | string                             | The full secret, shown once. |

## ApiKeyId

No description.

string (`pattern: "^key_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ApiKeyList

No description.

| Property      | Required | Type and constraints                          | Description |
| ------------- | -------- | --------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                      | —           |
| `data`        | Yes      | Array of [ApiKey](/reference/schemas/#apikey) | —           |
| `has_more`    | Yes      | boolean                                       | —           |
| `next_cursor` | Yes      | string or null                                | —           |

## ApiKeySecret

No description.

| Property                  | Required | Type and constraints                   | Description |
| ------------------------- | -------- | -------------------------------------- | ----------- |
| `api_key`                 | Yes      | [ApiKey](/reference/schemas/#apikey)   | —           |
| `secret`                  | Yes      | string                                 | Shown once. |
| `previous_key_expires_at` | No       | string or null (`format: "date-time"`) | —           |

## ApiKeySecretList

No description.

| Property | Required | Type and constraints                                                | Description |
| -------- | -------- | ------------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                            | —           |
| `data`   | Yes      | Array of [ApiKeyExtraSecret](/reference/schemas/#apikeyextrasecret) | —           |

## AttributeCatalogue

No description.

| Property     | Required | Type and constraints                    | Description |
| ------------ | -------- | --------------------------------------- | ----------- |
| `object`     | Yes      | string (`const: "attribute_catalogue"`) | —           |
| `attributes` | Yes      | Array of object                         | —           |

## AttributePreview

No description.

| Property     | Required | Type and constraints                  | Description                                                                       |
| ------------ | -------- | ------------------------------------- | --------------------------------------------------------------------------------- |
| `object`     | Yes      | string (`const: "attribute_preview"`) | —                                                                                 |
| `first_name` | Yes      | string                                | —                                                                                 |
| `last_name`  | Yes      | string                                | —                                                                                 |
| `groups`     | Yes      | Array of string                       | —                                                                                 |
| `attributes` | Yes      | object (`additionalProperties: true`) | The predefined catalog attributes that had a value.                               |
| `unmapped`   | Yes      | Array of string                       | Payload names (after the sign-in bounds) that no catalog attribute reads, sorted. |

## AttributePreviewRequest

One sample payload. `saml` reads `attributes` (each name with its values); `oidc` reads `claims` (an ID token or UserInfo claim set).

| Property     | Required | Type and constraints                                                                                        | Description |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------- | ----------- |
| `protocol`   | Yes      | string (`enum: ["saml","oidc"]`)                                                                            | —           |
| `attributes` | No       | object (`additionalProperties: {"type":"array","maxItems":256,"items":{"type":"string","maxLength":4096}}`) | —           |
| `claims`     | No       | object (`additionalProperties: true`)                                                                       | —           |

## AttributeTestPreview

No description.

| Property            | Required | Type and constraints                                                          | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------- | ----------- |
| `custom_attributes` | Yes      | [CustomAttributeValues](/reference/schemas/#customattributevalues)            | —           |
| `warnings`          | Yes      | Array of [CustomAttributeWarning](/reference/schemas/#customattributewarning) | —           |
| `source`            | Yes      | [AttributeTestSource](/reference/schemas/#attributetestsource)                | —           |

## AttributeTestSource

No description.

| Property   | Required | Type and constraints                                                                                                                                                                         | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `v`        | Yes      | integer (`const: 1`)                                                                                                                                                                         | —           |
| `protocol` | Yes      | string (`enum: ["saml","oidc"]`)                                                                                                                                                             | —           |
| `saml`     | No       | object (`additionalProperties: {"type":"array","items":{"type":"string"}}`)                                                                                                                  | —           |
| `oidc`     | No       | object (`additionalProperties: {"x-go-type":"json.RawMessage","description":"Authenticated primitive JSON or nested primitive arrays; unsupported object claims are represented by null."}`) | —           |

## AuditLog

No description.

| Property       | Required | Type and constraints                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------- | -------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Yes      | [AuditLogId](/reference/schemas/#auditlogid) | —                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `object`       | Yes      | string (`const: "audit_log"`)                | —                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `actor`        | Yes      | string                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `actor_label`  | No       | string                                       | A readable name for the actor, looked up when the page is read (never stored) - the member's email for `member:` actors, the key's name (or its display prefix when unnamed) for `api_key:` actors. Absent for other actors and for members or keys that no longer exist.                                                                                                                                                                               |
| `action`       | Yes      | string                                       | The action, e.g. `connection.activated`. Every action and its target types are listed in the published action catalogue (`dist/audit-actions.json` of the core build, scope `environment`); clients label rows from it and show an action they don't know by its raw name.                                                                                                                                                                              |
| `target`       | No       | string                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `target_label` | No       | string                                       | A readable name for the target - an organization's name, a domain, a connection's or directory's kind and organization, an API key's or M2M client's name, a webhook endpoint's URL, a role's name, a member's masked email (j***@acme.com), a setup link's organization. The current name when the target still exists, else the label the entry stored when it was written, so entries about deleted targets stay readable. Absent for other targets. |
| `created_at`   | Yes      | [Timestamp](/reference/schemas/#timestamp)   | —                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

## AuditLogContext

No description.

| Property     | Required | Type and constraints      | Description              |
| ------------ | -------- | ------------------------- | ------------------------ |
| `location`   | No       | string (`maxLength: 64`)  | The client's IP address. |
| `user_agent` | No       | string (`maxLength: 512`) | —                        |

## AuditLogEvent

No description.

| Property          | Required | Type and constraints                                        | Description |
| ----------------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`          | Yes      | string (`enum: ["audit_log_event"]`)                        | —           |
| `id`              | Yes      | [AuditLogEventId](/reference/schemas/#auditlogeventid)      | —           |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid)        | —           |
| `action`          | Yes      | string                                                      | —           |
| `version`         | Yes      | integer                                                     | —           |
| `occurred_at`     | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —           |
| `created_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —           |
| `actor`           | Yes      | [AuditLogParty](/reference/schemas/#auditlogparty)          | —           |
| `targets`         | Yes      | Array of [AuditLogParty](/reference/schemas/#auditlogparty) | —           |
| `context`         | Yes      | [AuditLogContext](/reference/schemas/#auditlogcontext)      | —           |
| `metadata`        | No       | [AuditLogMetadata](/reference/schemas/#auditlogmetadata)    | —           |

## AuditLogEventCreate

No description.

| Property          | Required | Type and constraints                                         | Description |
| ----------------- | -------- | ------------------------------------------------------------ | ----------- |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid)         | —           |
| `event`           | Yes      | [AuditLogEventInput](/reference/schemas/#auditlogeventinput) | —           |

## AuditLogEventExport

No description.

| Property      | Required | Type and constraints                                        | Description                                                         |
| ------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                   | —                                                                   |
| `data`        | Yes      | Array of [AuditLogEvent](/reference/schemas/#auditlogevent) | —                                                                   |
| `has_more`    | Yes      | boolean                                                     | —                                                                   |
| `next_before` | Yes      | string or null                                              | Pass as `before` to export the next rows; null when there are none. |

## AuditLogEventId

No description.

string (`pattern: "^ale_[0-9A-HJKMNP-TV-Z]{26}$"`)

## AuditLogEventInput

No description.

| Property      | Required | Type and constraints                                        | Description                                                     |
| ------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------- |
| `action`      | Yes      | string (`maxLength: 128`)                                   | —                                                               |
| `occurred_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —                                                               |
| `version`     | No       | integer (`minimum: 1`; `maximum: 10000`)                    | The schema version to validate against; the latest when absent. |
| `actor`       | Yes      | [AuditLogParty](/reference/schemas/#auditlogparty)          | —                                                               |
| `targets`     | Yes      | Array of [AuditLogParty](/reference/schemas/#auditlogparty) | —                                                               |
| `context`     | No       | [AuditLogContext](/reference/schemas/#auditlogcontext)      | —                                                               |
| `metadata`    | No       | [AuditLogMetadata](/reference/schemas/#auditlogmetadata)    | —                                                               |

## AuditLogEventList

No description.

| Property      | Required | Type and constraints                                        | Description |
| ------------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                   | —           |
| `data`        | Yes      | Array of [AuditLogEvent](/reference/schemas/#auditlogevent) | —           |
| `has_more`    | Yes      | boolean                                                     | —           |
| `next_cursor` | Yes      | string or null                                              | —           |

## AuditLogExport

No description.

| Property     | Required | Type and constraints                                     | Description |
| ------------ | -------- | -------------------------------------------------------- | ----------- |
| `id`         | Yes      | [AuditLogExportId](/reference/schemas/#auditlogexportid) | —           |
| `object`     | Yes      | string (`const: "audit_log_export"`)                     | —           |
| `state`      | Yes      | string (`enum: ["pending","ready","failed"]`)            | —           |
| `url`        | No       | string or null (`format: "uri"`)                         | —           |
| `expires_at` | No       | string or null (`format: "date-time"`)                   | —           |

## AuditLogExportCreate

No description.

| Property       | Required | Type and constraints                                 | Description                                                                                                                                    |
| -------------- | -------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`         | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —                                                                                                                                              |
| `to`           | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —                                                                                                                                              |
| `actor`        | No       | string                                               | —                                                                                                                                              |
| `action`       | No       | string                                               | —                                                                                                                                              |
| `target`       | No       | string                                               | —                                                                                                                                              |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | Environment exports only (`POST /v1/audit_logs/exports`); the same organization filter as `GET /v1/audit_logs`. The account export rejects it. |

## AuditLogExportId

No description.

string (`pattern: "^aexp_[0-9A-HJKMNP-TV-Z]{26}$"`)

## AuditLogId

No description.

string (`pattern: "^alog_[0-9A-HJKMNP-TV-Z]{26}$"`)

## AuditLogJSONSchema

A JSON Schema of the supported subset (type, properties, required, additionalProperties as a boolean, enum, const, minLength, maxLength, pattern, minimum, maximum, items, minItems, maxItems, $schema, title, description).

object (`additionalProperties: true`)

## AuditLogList

No description.

| Property      | Required | Type and constraints                              | Description |
| ------------- | -------- | ------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                          | —           |
| `data`        | Yes      | Array of [AuditLog](/reference/schemas/#auditlog) | —           |
| `has_more`    | Yes      | boolean                                           | —           |
| `next_cursor` | Yes      | string or null                                    | —           |

## AuditLogMetadata

Flat metadata; keys up to 40 characters; values are strings (up to 500 characters), numbers, booleans or null (anything else answers parameter_invalid).

object (`additionalProperties: true`)

## AuditLogParty

No description.

| Property   | Required | Type and constraints                                     | Description |
| ---------- | -------- | -------------------------------------------------------- | ----------- |
| `type`     | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,63}$"`)        | —           |
| `id`       | Yes      | string (`minLength: 1`; `maxLength: 256`)                | —           |
| `name`     | No       | string (`maxLength: 256`)                                | —           |
| `metadata` | No       | [AuditLogMetadata](/reference/schemas/#auditlogmetadata) | —           |

## AuditLogSchema

No description.

| Property     | Required | Type and constraints                                                      | Description |
| ------------ | -------- | ------------------------------------------------------------------------- | ----------- |
| `object`     | Yes      | string (`enum: ["audit_log_schema"]`)                                     | —           |
| `action`     | Yes      | string                                                                    | —           |
| `version`    | Yes      | integer                                                                   | —           |
| `actor`      | No       | [AuditLogSchemaActor](/reference/schemas/#auditlogschemaactor)            | —           |
| `targets`    | Yes      | Array of [AuditLogSchemaTarget](/reference/schemas/#auditlogschematarget) | —           |
| `metadata`   | No       | [AuditLogJSONSchema](/reference/schemas/#auditlogjsonschema)              | —           |
| `created_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                                | —           |

## AuditLogSchemaActor

No description.

| Property   | Required | Type and constraints                                         | Description |
| ---------- | -------- | ------------------------------------------------------------ | ----------- |
| `metadata` | No       | [AuditLogJSONSchema](/reference/schemas/#auditlogjsonschema) | —           |

## AuditLogSchemaCreate

No description.

| Property   | Required | Type and constraints                                                      | Description                                    |
| ---------- | -------- | ------------------------------------------------------------------------- | ---------------------------------------------- |
| `action`   | Yes      | string (`maxLength: 128`)                                                 | Lowercase dotted words, e.g. `user.signed_in`. |
| `actor`    | No       | [AuditLogSchemaActor](/reference/schemas/#auditlogschemaactor)            | —                                              |
| `targets`  | Yes      | Array of [AuditLogSchemaTarget](/reference/schemas/#auditlogschematarget) | —                                              |
| `metadata` | No       | [AuditLogJSONSchema](/reference/schemas/#auditlogjsonschema)              | —                                              |

## AuditLogSchemaList

No description.

| Property      | Required | Type and constraints                                          | Description |
| ------------- | -------- | ------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                     | —           |
| `data`        | Yes      | Array of [AuditLogSchema](/reference/schemas/#auditlogschema) | —           |
| `has_more`    | Yes      | boolean                                                       | —           |
| `next_cursor` | Yes      | string or null                                                | —           |

## AuditLogSchemaTarget

No description.

| Property   | Required | Type and constraints                                         | Description |
| ---------- | -------- | ------------------------------------------------------------ | ----------- |
| `type`     | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,63}$"`)            | —           |
| `metadata` | No       | [AuditLogJSONSchema](/reference/schemas/#auditlogjsonschema) | —           |

## AuthorizationBulkCheck

No description.

| Property | Required | Type and constraints                                                  | Description |
| -------- | -------- | --------------------------------------------------------------------- | ----------- |
| `checks` | Yes      | Array of [AuthorizationCheck](/reference/schemas/#authorizationcheck) | —           |

## AuthorizationBulkDecision

No description.

| Property | Required | Type and constraints                                                        | Description |
| -------- | -------- | --------------------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                                    | —           |
| `data`   | Yes      | Array of [AuthorizationDecision](/reference/schemas/#authorizationdecision) | —           |

## AuthorizationCheck

Name a `membership`, or a `user` and an `organization`.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `membership`   | No       | [MembershipId](/reference/schemas/#membershipid)     | —           |
| `user`         | No       | [EndUserId](/reference/schemas/#enduserid)           | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `permission`   | Yes      | [PermissionSlug](/reference/schemas/#permissionslug) | —           |
| `resource`     | No       | [AuthzResource](/reference/schemas/#authzresource)   | —           |

## AuthorizationDecision

No description.

| Property     | Required | Type and constraints                             | Description |
| ------------ | -------- | ------------------------------------------------ | ----------- |
| `object`     | Yes      | string (`const: "authorization_decision"`)       | —           |
| `authorized` | Yes      | boolean                                          | —           |
| `membership` | No       | [MembershipId](/reference/schemas/#membershipid) | —           |

## AuthzResource

No description.

| Property | Required | Type and constraints                                       | Description |
| -------- | -------- | ---------------------------------------------------------- | ----------- |
| `type`   | Yes      | [AuthzResourceType](/reference/schemas/#authzresourcetype) | —           |
| `id`     | Yes      | string (`minLength: 1`; `maxLength: 256`)                  | —           |

## AuthzResourceType

A kind of object in the developer's app, such as `document`.

string (`pattern: "^[a-z0-9][a-z0-9_.:-]{0,63}$"`)

## BotDetection

No description.

| Property       | Required | Type and constraints                                | Description                                    |
| -------------- | -------- | --------------------------------------------------- | ---------------------------------------------- |
| `object`       | Yes      | string (`const: "bot_detection"`)                   | —                                              |
| `id`           | Yes      | string (`pattern: "^bdet_[0-9A-HJKMNP-TV-Z]{26}$"`) | —                                              |
| `created_at`   | Yes      | string (`format: "date-time"`)                      | —                                              |
| `flow`         | Yes      | string (`enum: ["sign_in","sign_up"]`)              | —                                              |
| `action`       | Yes      | string (`enum: ["challenged","blocked"]`)           | —                                              |
| `challenge`    | Yes      | string or null (`enum: ["captcha","mfa",null]`)     | —                                              |
| `rule_id`      | Yes      | string or null                                      | —                                              |
| `reasons`      | Yes      | Array of string                                     | —                                              |
| `user`         | Yes      | string or null                                      | —                                              |
| `email_domain` | Yes      | string or null                                      | —                                              |
| `country`      | Yes      | string or null                                      | —                                              |
| `asn`          | Yes      | integer or null (`format: "int64"`)                 | —                                              |
| `network`      | Yes      | string or null                                      | The client's /24 (IPv4) or /48 (IPv6) network. |

## BotDetectionList

No description.

| Property      | Required | Type and constraints                                      | Description |
| ------------- | -------- | --------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                  | —           |
| `data`        | Yes      | Array of [BotDetection](/reference/schemas/#botdetection) | —           |
| `has_more`    | Yes      | boolean                                                   | —           |
| `next_cursor` | Yes      | string or null                                            | —           |

## BotProtectionSettings

No description.

| Property               | Required | Type and constraints                            | Description                                                                                                       |
| ---------------------- | -------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `object`               | Yes      | string (`const: "bot_protection"`)              | —                                                                                                                 |
| `captcha_mode`         | Yes      | string (`enum: ["off","adaptive","always"]`)    | `adaptive`: always on sign-up, on sign-in when recent failures raise the risk.                                    |
| `captcha_provider`     | Yes      | string (`enum: ["managed","own"]`)              | —                                                                                                                 |
| `turnstile_site_key`   | Yes      | string or null                                  | —                                                                                                                 |
| `turnstile_secret_set` | Yes      | boolean                                         | —                                                                                                                 |
| `device_tracking`      | Yes      | boolean                                         | A first-party device cookie, hashed with the user agent and network prefix, feeds the unrecognized-device signal. |
| `new_device_email`     | Yes      | boolean                                         | Email users after a sign-in from a new device.                                                                    |
| `rules`                | Yes      | Array of [BotRule](/reference/schemas/#botrule) | —                                                                                                                 |

## BotProtectionSettingsUpdate

No description.

| Property                 | Required | Type and constraints                            | Description                                                                                       |
| ------------------------ | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `captcha_mode`           | Yes      | string (`enum: ["off","adaptive","always"]`)    | —                                                                                                 |
| `captcha_provider`       | Yes      | string (`enum: ["managed","own"]`)              | —                                                                                                 |
| `turnstile_site_key`     | No       | string or null (`maxLength: 128`)               | —                                                                                                 |
| `turnstile_secret`       | No       | string (`minLength: 1`; `maxLength: 256`)       | The developer's Turnstile secret, sealed at rest and never returned. Omit to keep the stored one. |
| `clear_turnstile_secret` | No       | boolean                                         | —                                                                                                 |
| `device_tracking`        | Yes      | boolean                                         | —                                                                                                 |
| `new_device_email`       | Yes      | boolean                                         | —                                                                                                 |
| `rules`                  | Yes      | Array of [BotRule](/reference/schemas/#botrule) | —                                                                                                 |

## BotRule

One bot-protection rule. List kinds (`country`, `ip`, `asn`, `email_domain`) need `values`; velocity and repeat kinds need `threshold` and `window_seconds` and apply to sign-up only; `stale_account` needs `days`; `stale_account` and `unrecognized_device` run after the first factor, apply to sign-in only and can only `deny` or challenge with `mfa`.

| Property         | Required | Type and constraints                                                                                                                                                             | Description                                                                                                                       |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Yes      | string (`pattern: "^[a-z0-9_-]{1,64}$"`)                                                                                                                                         | —                                                                                                                                 |
| `kind`           | Yes      | string (`enum: ["country","ip","asn","email_domain","disposable_email","sign_up_velocity_ip","sign_up_velocity_domain","repeat_sign_up","stale_account","unrecognized_device"]`) | —                                                                                                                                 |
| `action`         | Yes      | string (`enum: ["allow","deny","challenge"]`)                                                                                                                                    | —                                                                                                                                 |
| `challenge`      | No       | string (`enum: ["captcha","mfa"]`)                                                                                                                                               | Required when action is challenge.                                                                                                |
| `enabled`        | Yes      | boolean                                                                                                                                                                          | —                                                                                                                                 |
| `flows`          | No       | Array of string (`enum: ["sign_in","sign_up"]`)                                                                                                                                  | —                                                                                                                                 |
| `values`         | No       | Array of string (`minLength: 1`; `maxLength: 253`)                                                                                                                               | ISO 3166-1 alpha-2 countries, IPs or CIDRs, ASNs (with or without "AS"), or email domains (a domain also matches its subdomains). |
| `not_in`         | No       | boolean                                                                                                                                                                          | Match when the value is not listed (an allow-list); an unknown country, address or ASN matches.                                   |
| `threshold`      | No       | integer (`minimum: 1`; `maximum: 1000000`)                                                                                                                                       | —                                                                                                                                 |
| `window_seconds` | No       | integer (`minimum: 60`; `maximum: 2592000`)                                                                                                                                      | —                                                                                                                                 |
| `days`           | No       | integer (`minimum: 1`; `maximum: 3650`)                                                                                                                                          | —                                                                                                                                 |

## Branding

No description.

| Property      | Required | Type and constraints                                     | Description                                                                                                         |
| ------------- | -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `object`      | Yes      | string (`const: "branding"`)                             | —                                                                                                                   |
| `app_name`    | No       | string or null (`maxLength: 100`)                        | The app name portal invite emails show ("Acme invited you…"); `null` until set, when the emails use a generic name. |
| `light`       | No       | [BrandingTheme](/reference/schemas/#brandingtheme)       | —                                                                                                                   |
| `dark`        | No       | [BrandingTheme](/reference/schemas/#brandingtheme)       | —                                                                                                                   |
| `logo_url`    | No       | string or null (`format: "uri"`)                         | —                                                                                                                   |
| `font`        | No       | string or null                                           | —                                                                                                                   |
| `radius`      | No       | integer or null                                          | —                                                                                                                   |
| `privacy_url` | No       | string or null (`format: "uri"`)                         | —                                                                                                                   |
| `terms_url`   | No       | string or null (`format: "uri"`)                         | —                                                                                                                   |
| `favicon_url` | No       | string or null (`format: "uri"`)                         | —                                                                                                                   |
| `font_url`    | No       | string or null (`format: "uri"`)                         | —                                                                                                                   |
| `surfaces`    | No       | [BrandingSurfaces](/reference/schemas/#brandingsurfaces) | —                                                                                                                   |

## BrandingAssetUpload

No description.

| Property | Required | Type and constraints                         | Description                                   |
| -------- | -------- | -------------------------------------------- | --------------------------------------------- |
| `data`   | Yes      | string (`minLength: 4`; `maxLength: 699052`) | The file, standard base64 (padding required). |

## BrandingColorPair

One color in the light and the dark scheme; an unset value is OhAuthCat's default for that scheme.

| Property | Required | Type and constraints                    | Description |
| -------- | -------- | --------------------------------------- | ----------- |
| `light`  | No       | string (`pattern: "^#[0-9a-fA-F]{6}$"`) | —           |
| `dark`   | No       | string (`pattern: "^#[0-9a-fA-F]{6}$"`) | —           |

## BrandingEmailColors

The email color set, accepted only on the `email` surface and only on the Business plan and above (other plans answer `plan_limit_reached`; on another surface it answers `parameter_invalid`). Every color is optional; unset colors are OhAuthCat's defaults, and an unset `accent` is the email surface's theme accent. Button text is picked automatically (white or the darker `text` color). A set below WCAG AA in either scheme answers `parameter_invalid` naming the failing color (for example `surfaces.email.colors.muted_text.dark`) and the pair. `text` and `muted_text` need 4.5:1 on `card_background`, button text 4.5:1 on `accent`, and `accent` 3:1 against `card_background`.

| Property          | Required | Type and constraints                                       | Description |
| ----------------- | -------- | ---------------------------------------------------------- | ----------- |
| `page_background` | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |
| `card_background` | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |
| `text`            | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |
| `muted_text`      | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |
| `accent`          | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |
| `border`          | No       | [BrandingColorPair](/reference/schemas/#brandingcolorpair) | —           |

## BrandingFavicon

No description.

| Property      | Required | Type and constraints                 | Description |
| ------------- | -------- | ------------------------------------ | ----------- |
| `object`      | Yes      | string (`const: "branding_favicon"`) | —           |
| `favicon_url` | Yes      | string (`format: "uri"`)             | —           |
| `size_bytes`  | Yes      | integer                              | —           |

## BrandingFont

No description.

| Property     | Required | Type and constraints              | Description |
| ------------ | -------- | --------------------------------- | ----------- |
| `object`     | Yes      | string (`const: "branding_font"`) | —           |
| `font_url`   | Yes      | string (`format: "uri"`)          | —           |
| `size_bytes` | Yes      | integer                           | —           |

## BrandingLogo

No description.

| Property       | Required | Type and constraints                           | Description                                                                        |
| -------------- | -------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| `object`       | Yes      | string (`const: "branding_logo"`)              | —                                                                                  |
| `logo_url`     | Yes      | string (`format: "uri"`)                       | The logo's URL on the assets host; set it as `logo_url` with `PATCH /v1/branding`. |
| `content_type` | Yes      | string (`enum: ["image/png","image/svg+xml"]`) | —                                                                                  |
| `width`        | Yes      | integer                                        | —                                                                                  |
| `height`       | Yes      | integer                                        | —                                                                                  |
| `size_bytes`   | Yes      | integer                                        | —                                                                                  |

## BrandingLogoUpload

No description.

| Property | Required | Type and constraints                         | Description                                                                       |
| -------- | -------- | -------------------------------------------- | --------------------------------------------------------------------------------- |
| `data`   | Yes      | string (`minLength: 4`; `maxLength: 349528`) | The PNG or SVG file, standard base64 (padding required). At most 256 KiB decoded. |

## BrandingSurface

A surface's branding; every field left out falls back to the main branding.

| Property        | Required | Type and constraints                                           | Description                                                                                                                                                                                                                                                                   |
| --------------- | -------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `light`         | No       | [BrandingTheme](/reference/schemas/#brandingtheme)             | —                                                                                                                                                                                                                                                                             |
| `dark`          | No       | [BrandingTheme](/reference/schemas/#brandingtheme)             | —                                                                                                                                                                                                                                                                             |
| `radius`        | No       | integer (`minimum: 0`; `maximum: 32`)                          | —                                                                                                                                                                                                                                                                             |
| `logo_url`      | No       | string (`format: "uri"`)                                       | A URL returned by `POST /v1/branding/logo` for this environment.                                                                                                                                                                                                              |
| `font`          | No       | string (`maxLength: 100`)                                      | —                                                                                                                                                                                                                                                                             |
| `favicon_url`   | No       | string (`format: "uri"`)                                       | A URL returned by `POST /v1/branding/favicon` for this environment.                                                                                                                                                                                                           |
| `font_url`      | No       | string (`format: "uri"`)                                       | A URL returned by `POST /v1/branding/font` for this environment.                                                                                                                                                                                                              |
| `logo_url_dark` | No       | string (`format: "uri"`)                                       | The logo shown in dark mode (emails render it on the email surface). A URL returned by `POST /v1/branding/logo` for this environment. Upload a logo made for a dark background for best results; without one, emails keep the main logo on a light rounded chip in dark mode. |
| `colors`        | No       | [BrandingEmailColors](/reference/schemas/#brandingemailcolors) | —                                                                                                                                                                                                                                                                             |

## BrandingSurfaces

Separate branding for the setup portal, the consent screen and emails, each falling back to the main branding field by field. On an update the object replaces the stored sets; `{}` removes them.

| Property  | Required | Type and constraints                                   | Description |
| --------- | -------- | ------------------------------------------------------ | ----------- |
| `portal`  | No       | [BrandingSurface](/reference/schemas/#brandingsurface) | —           |
| `consent` | No       | [BrandingSurface](/reference/schemas/#brandingsurface) | —           |
| `email`   | No       | [BrandingSurface](/reference/schemas/#brandingsurface) | —           |

## BrandingTheme

Theme colours as hex (`#rgb` or `#rrggbb`). The portal themes `primary` only (DESIGN.md §6); it always uses its own neutral surfaces and text. The hosted consent screen uses all four (`accent`, or else `primary`, as its accent); unset colours are the product defaults. A theme whose `foreground` or accent has a contrast below 4.5:1 (WCAG AA) on its `background` (or the default background) answers `parameter_invalid` naming the failing colour, for example `light.foreground`.

| Property     | Required | Type and constraints | Description                                                                                       |
| ------------ | -------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `primary`    | No       | string               | —                                                                                                 |
| `background` | No       | string               | Stored and returned for compatibility; the portal ignores it (its surfaces are never themed).     |
| `foreground` | No       | string               | Stored and returned for compatibility; the portal ignores it (its text colours are never themed). |
| `accent`     | No       | string               | —                                                                                                 |

## BrandingUpdate

A partial update. An absent field is kept; an explicit `null` (or `""` for a string) clears it.

| Property      | Required | Type and constraints                                     | Description                                                                                                                                                                                                         |
| ------------- | -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_name`    | No       | string or null (`maxLength: 100`)                        | The app name shown in portal invite emails, 1–100 characters without control characters.                                                                                                                            |
| `light`       | No       | [BrandingTheme](/reference/schemas/#brandingtheme)       | —                                                                                                                                                                                                                   |
| `dark`        | No       | [BrandingTheme](/reference/schemas/#brandingtheme)       | —                                                                                                                                                                                                                   |
| `logo_url`    | No       | string or null (`format: "uri"`)                         | A URL returned by `POST /v1/branding/logo` for this environment (logos are served only from the assets host); any other URL answers `parameter_invalid`. `null` or `""` removes the logo.                           |
| `font`        | No       | string or null                                           | A font family name of at most 100 characters without `;{}&lt;&gt;"'\\()/*@:` or control characters. The hosted consent screen recognises `system`, `serif` and `mono` and uses the system font for any other value. |
| `radius`      | No       | integer or null (`minimum: 0`; `maximum: 32`)            | Corner radius in pixels. Values above 12 are accepted for compatibility but the portal renders at most 12 (DESIGN.md §6) and the hosted consent screen at most 16; new values should be 0–12.                       |
| `privacy_url` | No       | string or null (`format: "uri"`)                         | —                                                                                                                                                                                                                   |
| `terms_url`   | No       | string or null (`format: "uri"`)                         | —                                                                                                                                                                                                                   |
| `favicon_url` | No       | string or null (`format: "uri"`)                         | A URL returned by `POST /v1/branding/favicon` for this environment; `null` or `""` removes it.                                                                                                                      |
| `font_url`    | No       | string or null (`format: "uri"`)                         | A URL returned by `POST /v1/branding/font` for this environment; `null` or `""` removes it.                                                                                                                         |
| `surfaces`    | No       | [BrandingSurfaces](/reference/schemas/#brandingsurfaces) | —                                                                                                                                                                                                                   |

## Certificate

No description.

| Property      | Required | Type and constraints                       | Description                     |
| ------------- | -------- | ------------------------------------------ | ------------------------------- |
| `fingerprint` | Yes      | string (`pattern: "^[0-9a-f]{64}$"`)       | SHA-256 of the DER certificate. |
| `object`      | Yes      | string (`const: "certificate"`)            | —                               |
| `subject`     | No       | string                                     | —                               |
| `not_before`  | No       | [Timestamp](/reference/schemas/#timestamp) | —                               |
| `not_after`   | Yes      | [Timestamp](/reference/schemas/#timestamp) | —                               |
| `created_at`  | No       | [Timestamp](/reference/schemas/#timestamp) | —                               |

## CertificateCreate

No description.

| Property          | Required | Type and constraints    | Description |
| ----------------- | -------- | ----------------------- | ----------- |
| `certificate_pem` | Yes      | string (`minLength: 1`) | —           |

## CertificateList

No description.

| Property      | Required | Type and constraints                                    | Description |
| ------------- | -------- | ------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                | —           |
| `data`        | Yes      | Array of [Certificate](/reference/schemas/#certificate) | —           |
| `has_more`    | Yes      | boolean                                                 | —           |
| `next_cursor` | Yes      | string or null                                          | —           |

## Connection

No description.

| Property                | Required | Type and constraints                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | -------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `oidc_managed`          | No       | [ConnectionManagedOIDC](/reference/schemas/#connectionmanagedoidc)             | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `catalogue_idp`         | No       | [PortalIDPId](/reference/schemas/#portalidpid)                                 | Explicit backend catalogue selection; never inferred from issuer URLs, protocol or imported metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `id`                    | Yes      | [ConnectionId](/reference/schemas/#connectionid)                               | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `object`                | Yes      | string (`const: "connection"`)                                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `legacy_ids`            | No       | [LegacyIds](/reference/schemas/#legacyids)                                     | IDs of this object in the system it was imported from, by source (e.g. `{"workos":"org_…"}`); absent when it was not imported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `forwarding`            | No       | [ConnectionForwarding](/reference/schemas/#connectionforwarding)               | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `idp_initiated`         | No       | [ConnectionIDPInitiated](/reference/schemas/#connectionidpinitiated)           | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `organization_id`       | No       | [OrganizationId](/reference/schemas/#organizationid)                           | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `name`                  | No       | string                                                                         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `type`                  | Yes      | string (`enum: ["saml","oidc"]`)                                               | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `state`                 | Yes      | string (`enum: ["draft","pending_test","tested","active","inactive","error"]`) | `draft`: not configured. `pending_test`: IdP configuration present, no passed test sign-in yet. `tested`: a test passed, not active. `active`/`inactive`: as set. `error`: the connection cannot sign in (stored error state, or every IdP certificate has expired). Clients must tolerate values added later.                                                                                                                                                                                                                                                                                                |
| `sp_entity_id`          | No       | string                                                                         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `sp_metadata_url`       | No       | string (`format: "uri"`)                                                       | The public SP metadata of a SAML connection on the primary broker host (an IdP can import it by URL). Served for drafts too. Absent on OIDC connections.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `test_idp`              | No       | boolean                                                                        | True when the connection signs in through OhAuthCat's sandbox test IdP (its IdP entity ID or OIDC issuer is the test IdP's). Lets the dashboard find the sandbox's test connection without matching on idp_entity_id. Absent when false.                                                                                                                                                                                                                                                                                                                                                                      |
| `acs_urls`              | No       | Array of string                                                                | The URLs the IdP sends sign-ins to, primary first. SAML: the ACS URL on the primary broker host (index 0), then on the standby host (index 1), then the same pair for each legacy ACS alias. OIDC: the redirect URI on the primary broker host (index 0), then the standby redirect URI (index 1); register both in the IdP application. A managed connection (oidc_managed) returns its provider's fixed redirect URIs instead (/sso/oidc/managed/callback/google or /microsoft on the primary, then the standby broker host), which OhAuthCat registers in its own app; there is nothing to register.       |
| `sp_slo_urls`           | No       | Array of string                                                                | Our SAML SingleLogoutService locations to register at the IdP: the primary broker host, then the standby host, then each verified custom broker host the connection receives sign-ins on. Returned on SAML connections by the portal connection routes (`GET`/`PATCH /portal/connections/{conn}`); absent on OIDC connections and elsewhere (see `GET /v1/connections/{conn}/single_logout`).                                                                                                                                                                                                                 |
| `routing_domains`       | No       | Array of string                                                                | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `standby_registered`    | No       | boolean                                                                        | The IT admin confirmed the standby URL (`acs_urls[1]`) is registered in the IdP: the standby ACS URL of a SAML connection, the standby redirect URI of an OIDC connection. Until then, sign-ins arriving on the standby host are refused.                                                                                                                                                                                                                                                                                                                                                                     |
| `import_source`         | No       | string                                                                         | The system an imported connection came from (the same key as in `legacy_ids`, e.g. `workos`, `polis`, `generic`). Absent when the connection was not imported. Clients must tolerate values added later.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `import_lever`          | No       | string (`enum: ["A","B","C","D"]`)                                             | The migration lever the import chose for an imported connection. `A`: the old sign-in URLs move to us (custom-domain takeover); the IT admin supplies the IdP metadata when the source could not export it, and changes nothing else in the IdP. `B`: the IdP configuration stays unchanged except the ACS URL and SP entity ID, which the IT admin replaces with ours. `C`: a re-setup with the same IdP application. `D`: the app forwards responses from its own ACS. Absent when the connection was not imported or was imported before the lever was recorded. Clients must tolerate values added later. |
| `standby_acs_selection` | No       | [StandbyACSSelection](/reference/schemas/#standbyacsselection)                 | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `idp_entity_id`         | No       | string or null                                                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `oidc_issuer`           | No       | string or null                                                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `metadata_stale_since`  | No       | string or null (`format: "date-time"`)                                         | Set when refreshing the IdP metadata from its URL has failed for 7 days or more; the time of the first failure. A warning only: sign-ins continue with the current certificates. Null otherwise.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `untested_since`        | No       | string or null (`format: "date-time"`)                                         | Set on an active connection whose IdP configuration was changed through the API or the portal after its last passed test sign-in; the time of the change. The connection stays active and keeps signing in; a new passed test clears it. Null otherwise.                                                                                                                                                                                                                                                                                                                                                      |
| `created_at`            | Yes      | [Timestamp](/reference/schemas/#timestamp)                                     | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `updated_at`            | No       | [Timestamp](/reference/schemas/#timestamp)                                     | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## ConnectionClientKey

No description.

| Property     | Required | Type and constraints                           | Description                                      |
| ------------ | -------- | ---------------------------------------------- | ------------------------------------------------ |
| `kid`        | Yes      | string                                         | —                                                |
| `state`      | Yes      | string (`enum: ["next","current","retiring"]`) | —                                                |
| `cert_pem`   | Yes      | string                                         | Self-signed X.509 certificate of the public key. |
| `jwk`        | Yes      | object (`additionalProperties: true`)          | The public key as a JWK (RFC 7517), with x5c.    |
| `created_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)     | —                                                |

## ConnectionClientKeys

No description.

| Property        | Required | Type and constraints                                                    | Description |
| --------------- | -------- | ----------------------------------------------------------------------- | ----------- |
| `object`        | Yes      | string (`const: "connection_client_keys"`)                              | —           |
| `connection_id` | Yes      | [ConnectionId](/reference/schemas/#connectionid)                        | —           |
| `jwks_uri`      | Yes      | string (`format: "uri"`)                                                | —           |
| `keys`          | Yes      | Array of [ConnectionClientKey](/reference/schemas/#connectionclientkey) | —           |

## ConnectionCreate

No description.

| Property             | Required | Type and constraints                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------- | -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization`       | Yes      | [OrganizationId](/reference/schemas/#organizationid)                 | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `name`               | No       | string                                                               | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `type`               | Yes      | string (`enum: ["saml","oidc"]`)                                     | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `saml_metadata_url`  | No       | string (`format: "uri"`)                                             | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `saml_metadata_xml`  | No       | string                                                               | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `saml_manual`        | No       | object                                                               | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `oidc_discovery_url` | No       | string (`format: "uri"`)                                             | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `oidc_client_id`     | No       | string                                                               | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `oidc_client_secret` | No       | string                                                               | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `routing_domains`    | No       | Array of string                                                      | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `idp_initiated`      | No       | [ConnectionIDPInitiated](/reference/schemas/#connectionidpinitiated) | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `oidc_managed`       | No       | [ConnectionManagedOIDC](/reference/schemas/#connectionmanagedoidc)   | —                                                                                                                                                                                                                                                                                                                                                                                           |
| `catalogue_idp`      | No       | [PortalIDPId](/reference/schemas/#portalidpid)                       | Optional explicit catalogue selection, such as the IdP the developer picked in the dashboard wizard; never inferred from the IdP configuration. It must name a catalogue IdP that offers SSO over the connection's type, or the request answers parameter_invalid. The portal's edit flow offers the matching setup steps for it; a connection without one stays editable through this API. |

## ConnectionForwarding

Lever D (forwarded responses from the app's own ACS or OIDC callback).

| Property            | Required | Type and constraints                   | Description                                                                                                                                                                            |
| ------------------- | -------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acs_urls`          | No       | Array of string (`format: "uri"`)      | —                                                                                                                                                                                      |
| `redirect_uris`     | No       | Array of string (`format: "uri"`)      | —                                                                                                                                                                                      |
| `until`             | No       | string or null (`format: "date-time"`) | Forwarding is accepted until this time; null when off.                                                                                                                                 |
| `expires_in_days`   | No       | integer or null (`minimum: 0`)         | Whole days left before `until` (rounded up; 0 once it has passed); null when forwarding is off.                                                                                        |
| `last_warning_days` | No       | integer or null                        | The last expiry warning mailed to the environment's owners and admins for the current `until` (30, 7 or 1 days before it); null when none yet. A new `until` starts the warnings over. |
| `hint`              | No       | string or null                         | While `until` is set, how to move the connection to Lever B (a direct IdP setup) before forwarding ends; null when forwarding is off.                                                  |

## ConnectionForwardingUpdate

Lever D settings, replaced as a whole when sent. `until` must be in the future and at most 12 months away; null or absent turns forwarding off. Absent URL lists keep the current ones. SAML connections need at least one `acs_urls` entry and OIDC connections one `redirect_uris` entry while forwarding is on.

| Property        | Required | Type and constraints                   | Description |
| --------------- | -------- | -------------------------------------- | ----------- |
| `acs_urls`      | No       | Array of string (`format: "uri"`)      | —           |
| `redirect_uris` | No       | Array of string (`format: "uri"`)      | —           |
| `until`         | No       | string or null (`format: "date-time"`) | —           |

## ConnectionHealth

Informational current health only; never changes authentication or policy. Observations cover the preceding 24 hours, excluding test sign-ins. Missing or insufficient data is explicit. Standby coverage means configured registration, not proven failover.

| Property       | Required | Type and constraints                                                    | Description |
| -------------- | -------- | ----------------------------------------------------------------------- | ----------- |
| `object`       | Yes      | string (`const: "connection_health"`)                                   | —           |
| `connection`   | Yes      | [ConnectionId](/reference/schemas/#connectionid)                        | —           |
| `observed_at`  | Yes      | string (`format: "date-time"`)                                          | —           |
| `window_start` | Yes      | string (`format: "date-time"`)                                          | —           |
| `score`        | No       | integer (`minimum: 0`; `maximum: 100`)                                  | —           |
| `status`       | Yes      | string (`enum: ["healthy","degraded","unhealthy","insufficient_data"]`) | —           |
| `factors`      | Yes      | Array of object (`additionalProperties: false`)                         | —           |

## ConnectionHealthList

No description.

| Property      | Required | Type and constraints                                              | Description |
| ------------- | -------- | ----------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                          | —           |
| `data`        | Yes      | Array of [ConnectionHealth](/reference/schemas/#connectionhealth) | —           |
| `has_more`    | Yes      | boolean                                                           | —           |
| `next_cursor` | Yes      | string or null                                                    | —           |

## ConnectionIDPInitiated

SAML only, off by default. Enabling or editing requires Business. While enabled, client_id must be a live publishable key in this environment and default_redirect_uri must exactly match a registered redirect. The broker always requires an account confirmation before sending a short single-use handoff ticket to that URI. Apps bind the ticket to their normal caller-PKCE authorize flow. Saving disabled removes the configuration; an absent object leaves it unchanged. Existing enabled settings keep being enforced after a plan downgrade.

| Property               | Required | Type and constraints                                        | Description |
| ---------------------- | -------- | ----------------------------------------------------------- | ----------- |
| `enabled`              | Yes      | boolean (`default: false`)                                  | —           |
| `client_id`            | No       | string (`minLength: 1`; `maxLength: 256`)                   | —           |
| `default_redirect_uri` | No       | string (`format: "uri"`; `minLength: 1`; `maxLength: 2048`) | —           |

## ConnectionId

No description.

string (`pattern: "^conn_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ConnectionList

No description.

| Property      | Required | Type and constraints                                  | Description |
| ------------- | -------- | ----------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                              | —           |
| `data`        | Yes      | Array of [Connection](/reference/schemas/#connection) | —           |
| `has_more`    | Yes      | boolean                                               | —           |
| `next_cursor` | Yes      | string or null                                        | —           |

## ConnectionManagedOIDC

Sign in with Google Workspace or Microsoft Entra through OhAuthCat's own multi-tenant app: no per-customer IdP app. Set on an OIDC connection instead of oidc_discovery_url, oidc_client_id and oidc_client_secret. Every token is bound to the organization: Google's hd claim, and the email domain, must be domains the organization verified; Microsoft Entra's tid must be entra_tenant_id. Personal accounts are refused unless allow_personal_accounts is true (the verified-domain rule still applies).

| Property                  | Required | Type and constraints                                    | Description                                                                               |
| ------------------------- | -------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `provider`                | Yes      | string (`enum: ["google_workspace","microsoft_entra"]`) | —                                                                                         |
| `entra_tenant_id`         | No       | string                                                  | The organization's Microsoft Entra tenant ID (a GUID); required for microsoft_entra only. |
| `allow_personal_accounts` | No       | boolean (`default: false`)                              | —                                                                                         |

## ConnectionSCIMBinding

No description.

| Property       | Required | Type and constraints                                                | Description |
| -------------- | -------- | ------------------------------------------------------------------- | ----------- |
| `directory_id` | Yes      | [DirectoryId](/reference/schemas/#directoryid)                      | —           |
| `match_key`    | No       | string (`enum: ["externalId","userName"]`; `default: "externalId"`) | —           |

## ConnectionShare

No description.

| Property                | Required | Type and constraints                                       | Description |
| ----------------------- | -------- | ---------------------------------------------------------- | ----------- |
| `id`                    | Yes      | [ConnectionShareId](/reference/schemas/#connectionshareid) | —           |
| `object`                | Yes      | string (`const: "connection_share"`)                       | —           |
| `connection_id`         | Yes      | [ConnectionId](/reference/schemas/#connectionid)           | —           |
| `owner_organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid)       | —           |
| `organization_id`       | Yes      | [OrganizationId](/reference/schemas/#organizationid)       | —           |
| `routing_domains`       | Yes      | Array of string                                            | —           |
| `created_at`            | Yes      | string (`format: "date-time"`)                             | —           |
| `revoked_at`            | No       | string (`format: "date-time"`)                             | —           |

## ConnectionShareCreate

No description.

| Property          | Required | Type and constraints                                 | Description                                                               |
| ----------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------- |
| `organization`    | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                                         |
| `routing_domains` | Yes      | Array of string                                      | Domains the target organization verified; sign-ins for them route to it.  |
| `owner_consent`   | Yes      | boolean                                              | Must be true; records that the owner organization consented to the share. |

## ConnectionShareId

No description.

string (`pattern: "^cshr_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ConnectionShareList

No description.

| Property | Required | Type and constraints                                            | Description |
| -------- | -------- | --------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                        | —           |
| `data`   | Yes      | Array of [ConnectionShare](/reference/schemas/#connectionshare) | —           |

## ConnectionTest

No description.

| Property     | Required | Type and constraints                       | Description                                                                              |
| ------------ | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `test_url`   | Yes      | string (`format: "uri"`)                   | —                                                                                        |
| `expires_at` | No       | [Timestamp](/reference/schemas/#timestamp) | —                                                                                        |
| `attempt_id` | No       | [SignInId](/reference/schemas/#signinid)   | This attempt; the test result's attempt_id matches it once the test sign-in is recorded. |
| `started_at` | No       | [Timestamp](/reference/schemas/#timestamp) | —                                                                                        |

## ConnectionTestStart

No description.

| Property      | Required | Type and constraints                                                                                                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scenario`    | No       | string (`enum: ["sp_initiated","idp_initiated","guest_domain","bad_signature","expired","wrong_audience","missing_email","rotated_cert","expiring_cert","revoked_user"]`)            | A sandbox test IdP outcome (sandbox environments and test IdP connections only). `rotated_cert` signs with the test IdP's rotated key (refused with `saml_signature_invalid` until the connection trusts the rotated certificate) and `expiring_cert` with a key whose certificate expires within days, so a certificate rollover and the expiry alerts can be rehearsed; `revoked_user` is the IdP refusing a user whose access it revoked (`saml_idp_status_error`, or `oidc_token_exchange_failed` for OIDC). |
| `time_shift`  | No       | string (`maxLength: 16`; `pattern: "^-?[0-9]+(\\.[0-9]+)?(ns&#124;us&#124;µs&#124;ms&#124;s&#124;m&#124;h)([0-9]+(\\.[0-9]+)?(ns&#124;us&#124;µs&#124;ms&#124;s&#124;m&#124;h))*$"`) | Time travel for the sandbox test IdP (sandbox environments and test IdP connections only), a duration such as `-10m` or `2h`, at most 24h either way. Only the test IdP's clock moves; documents outside the broker's skew allowance are refused as they would be from a real IdP with a wrong clock.                                                                                                                                                                                                            |
| `certificate` | No       | string (`enum: ["current","rotated","expiring"]`)                                                                                                                                    | The certificate the sandbox test IdP signs with (sandbox environments and test IdP connections only). `rotated` and `expiring` let a certificate rollover be rehearsed with any scenario; with `rotated_cert` or `expiring_cert` it must name that scenario's key (parameter_invalid otherwise).                                                                                                                                                                                                                 |

## ConnectionUpdate

No description.

| Property                | Required | Type and constraints                                                         | Description                                                                                                                                                                                                                                                 |
| ----------------------- | -------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | No       | string                                                                       | —                                                                                                                                                                                                                                                           |
| `saml_metadata_url`     | No       | string (`format: "uri"`)                                                     | —                                                                                                                                                                                                                                                           |
| `saml_metadata_xml`     | No       | string                                                                       | —                                                                                                                                                                                                                                                           |
| `oidc_client_id`        | No       | string                                                                       | —                                                                                                                                                                                                                                                           |
| `oidc_client_secret`    | No       | string                                                                       | —                                                                                                                                                                                                                                                           |
| `sp_entity_id`          | No       | string                                                                       | Override for migrated connections (the audience the IdP already sends, Levers A and D). Allowed on an imported connection or one with forwarding set; an absolute URI or URN of at most 1024 characters. The connection's default value is always accepted. |
| `standby_acs_selection` | No       | [StandbyACSSelection](/reference/schemas/#standbyacsselection)               | —                                                                                                                                                                                                                                                           |
| `forwarding`            | No       | [ConnectionForwardingUpdate](/reference/schemas/#connectionforwardingupdate) | —                                                                                                                                                                                                                                                           |
| `idp_initiated`         | No       | [ConnectionIDPInitiated](/reference/schemas/#connectionidpinitiated)         | —                                                                                                                                                                                                                                                           |
| `routing_domains`       | No       | Array of string                                                              | —                                                                                                                                                                                                                                                           |

## CustomAttributeMap

No description.

| Property   | Required | Type and constraints                                                          | Description |
| ---------- | -------- | ----------------------------------------------------------------------------- | ----------- |
| `mappings` | Yes      | Array of [CustomAttributeMapping](/reference/schemas/#customattributemapping) | —           |

## CustomAttributeMapping

No description.

| Property    | Required | Type and constraints                                             | Description                                                                                                                                           |
| ----------- | -------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attribute` | Yes      | string (`pattern: "^[a-z][a-z0-9_]{0,63}$"`)                     | —                                                                                                                                                     |
| `source`    | Yes      | string (`minLength: 1`; `maxLength: 1024`)                       | Exact SAML attribute, OIDC claim or directory SCIM source path; 1–1024 UTF-8 bytes without control characters. It is never executed as an expression. |
| `transform` | Yes      | string (`enum: ["none","trim","lowercase","uppercase","first"]`) | —                                                                                                                                                     |

## CustomAttributeValue

No description.

[See the full composed schema](/spec/openapi-v1.yaml)

## CustomAttributeValues

Output-only mapped application data, bounded to 32 KiB. Invalid values are omitted and never promote verified sign-in evidence. Missing keys clear previous mapped values.

object (`additionalProperties: {"$ref":"#/components/schemas/CustomAttributeValue"}`)

## CustomAttributeWarning

No description.

| Property    | Required | Type and constraints                                            | Description |
| ----------- | -------- | --------------------------------------------------------------- | ----------- |
| `attribute` | Yes      | string (`pattern: "^[a-z][a-z0-9_]{0,63}$"`)                    | —           |
| `reason`    | Yes      | string (`enum: ["missing","invalid","bounds","object_budget"]`) | —           |

## CustomDomain

No description.

| Property      | Required | Type and constraints                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | Yes      | [CustomDomainId](/reference/schemas/#customdomainid)                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `object`      | Yes      | string (`const: "custom_domain"`)                                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `type`        | Yes      | string (`enum: ["portal","broker","scim","email","signin","broker_scim"]`) | `signin` (Pro and above) serves the environment's hosted sign-in app on the hostname; once verified it is accepted as a sign-in API (CORS) and passkey origin for that environment only. `broker_scim` (Business and above) serves sign-in and SCIM on one hostname, as a vendor that did both on one host (a self-hosted Polis) did: paths under `/scim/` and the legacy SCIM base paths of imported directories reach SCIM only, every other path reaches sign-in only. |
| `hostname`    | Yes      | string                                                                     | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `state`       | Yes      | string (`enum: ["pending","active","failed"]`)                             | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `dns_records` | Yes      | Array of [DnsRecord](/reference/schemas/#dnsrecord)                        | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `created_at`  | No       | [Timestamp](/reference/schemas/#timestamp)                                 | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

## CustomDomainCreate

No description.

| Property       | Required | Type and constraints                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------- | -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | Yes      | string (`enum: ["portal","broker","scim","email","signin","broker_scim"]`) | `signin` (Pro and above) serves the environment's hosted sign-in app on the hostname; once verified it is accepted as a sign-in API (CORS) and passkey origin for that environment only. `broker_scim` (Business and above) serves sign-in and SCIM on one hostname, as a vendor that did both on one host (a self-hosted Polis) did: paths under `/scim/` and the legacy SCIM base paths of imported directories reach SCIM only, every other path reaches sign-in only. |
| `hostname`     | Yes      | string (`minLength: 1`; `maxLength: 253`)                                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `spf_record`   | No       | string (`minLength: 1`; `maxLength: 1024`)                                 | Email only. Exact SPF TXT configuration to verify at the sender domain.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `dkim_records` | No       | Array of [DnsRecord](/reference/schemas/#dnsrecord)                        | Email only. Exact DKIM TXT or CNAME configuration records.                                                                                                                                                                                                                                                                                                                                                                                                                |

## CustomDomainId

No description.

string (`pattern: "^cdom_[0-9A-HJKMNP-TV-Z]{26}$"`)

## CustomDomainList

No description.

| Property      | Required | Type and constraints                                      | Description |
| ------------- | -------- | --------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                  | —           |
| `data`        | Yes      | Array of [CustomDomain](/reference/schemas/#customdomain) | —           |
| `has_more`    | Yes      | boolean                                                   | —           |
| `next_cursor` | Yes      | string or null                                            | —           |

## DebugBundle

No description.

| Property               | Required | Type and constraints                               | Description |
| ---------------------- | -------- | -------------------------------------------------- | ----------- |
| `id`                   | Yes      | [DebugBundleId](/reference/schemas/#debugbundleid) | —           |
| `sign_in`              | Yes      | [SignInId](/reference/schemas/#signinid)           | —           |
| `connection`           | Yes      | [ConnectionId](/reference/schemas/#connectionid)   | —           |
| `created_at`           | Yes      | [Timestamp](/reference/schemas/#timestamp)         | —           |
| `expires_at`           | Yes      | [Timestamp](/reference/schemas/#timestamp)         | —           |
| `diagnostic_available` | Yes      | boolean                                            | —           |

## DebugBundleCreate

No description.

| Property  | Required | Type and constraints                     | Description |
| --------- | -------- | ---------------------------------------- | ----------- |
| `sign_in` | Yes      | [SignInId](/reference/schemas/#signinid) | —           |

## DebugBundleDocument

Diagnostic copy; redaction changes XML and it is not a cryptographically valid SAML message. No original XML, JWT or claim body is included.

| Property            | Required | Type and constraints                                 | Description                                                                                                              |
| ------------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `sign_in`           | Yes      | [SignInId](/reference/schemas/#signinid)             | —                                                                                                                        |
| `checks`            | Yes      | Array of string (`maxLength: 64`)                    | —                                                                                                                        |
| `checks_available`  | Yes      | boolean                                              | False for historical attempts without recorded validator invocation evidence. Timeline stages are not validation checks. |
| `timeline`          | Yes      | [SignInTimeline](/reference/schemas/#signintimeline) | —                                                                                                                        |
| `failing_invariant` | Yes      | string (`maxLength: 256`)                            | —                                                                                                                        |
| `idp_metadata`      | Yes      | object (`additionalProperties: false`)               | —                                                                                                                        |
| `saml_response`     | No       | string (`maxLength: 262144`)                         | —                                                                                                                        |
| `assertion`         | No       | string (`maxLength: 262144`)                         | —                                                                                                                        |

## DebugBundleId

No description.

string (`pattern: "^dbgb_[0-9A-HJKMNP-TV-Z]{26}$"`)

## DebugBundleList

No description.

| Property      | Required | Type and constraints                                                  | Description |
| ------------- | -------- | --------------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                              | —           |
| `data`        | Yes      | Array of [DebugBundleSummary](/reference/schemas/#debugbundlesummary) | —           |
| `has_more`    | Yes      | boolean                                                               | —           |
| `next_cursor` | Yes      | string or null                                                        | —           |

## DebugBundleShare

No description.

| Property     | Required | Type and constraints                       | Description |
| ------------ | -------- | ------------------------------------------ | ----------- |
| `url`        | Yes      | string (`format: "uri"`)                   | —           |
| `expires_at` | Yes      | [Timestamp](/reference/schemas/#timestamp) | —           |

## DebugBundleShareRevocation

No description.

| Property  | Required | Type and constraints                               | Description                          |
| --------- | -------- | -------------------------------------------------- | ------------------------------------ |
| `bundle`  | Yes      | [DebugBundleId](/reference/schemas/#debugbundleid) | —                                    |
| `revoked` | Yes      | integer (`minimum: 0`)                             | Live share links ended by this call. |

## DebugBundleSummary

No description.

| Property     | Required | Type and constraints                               | Description |
| ------------ | -------- | -------------------------------------------------- | ----------- |
| `id`         | Yes      | [DebugBundleId](/reference/schemas/#debugbundleid) | —           |
| `sign_in`    | Yes      | [SignInId](/reference/schemas/#signinid)           | —           |
| `connection` | Yes      | [ConnectionId](/reference/schemas/#connectionid)   | —           |
| `created_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)         | —           |
| `expires_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)         | —           |

## DebugCapture

Origin-local diagnostic capture reports captured N of 20; sign-ins served by other regions or during an outage are not captured.

| Property     | Required | Type and constraints                       | Description |
| ------------ | -------- | ------------------------------------------ | ----------- |
| `active`     | Yes      | boolean                                    | —           |
| `captured`   | Yes      | integer (`minimum: 0`; `maximum: 20`)      | —           |
| `expires_at` | No       | [Timestamp](/reference/schemas/#timestamp) | —           |
| `remaining`  | Yes      | integer (`minimum: 0`; `maximum: 20`)      | —           |

## DebugEmptyRequest

No description.

| Property | Required | Type and constraints | Description |
| -------- | -------- | -------------------- | ----------- |

## Deleted

No description.

| Property  | Required | Type and constraints    | Description |
| --------- | -------- | ----------------------- | ----------- |
| `id`      | Yes      | string                  | —           |
| `deleted` | Yes      | boolean (`const: true`) | —           |

## DevEvent

No description.

| Property     | Required | Type and constraints                   | Description |
| ------------ | -------- | -------------------------------------- | ----------- |
| `object`     | Yes      | string (`const: "dev_event"`)          | —           |
| `id`         | Yes      | [EventId](/reference/schemas/#eventid) | —           |
| `type`       | Yes      | string                                 | —           |
| `created_at` | Yes      | string (`format: "date-time"`)         | —           |

## DevInit

No description.

| Property               | Required | Type and constraints                                  | Description                                                                                              |
| ---------------------- | -------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `object`               | Yes      | string (`const: "dev_init"`)                          | —                                                                                                        |
| `environment`          | Yes      | [Environment](/reference/schemas/#environment)        | —                                                                                                        |
| `redirect_uri`         | No       | [See the full composed schema](/spec/openapi-v1.yaml) | —                                                                                                        |
| `redirect_uri_created` | Yes      | boolean                                               | —                                                                                                        |
| `relay_path`           | Yes      | string                                                | The relay WebSocket path on the API host (`/v1/dev/relay`).                                              |
| `organization`         | No       | [Organization](/reference/schemas/#organization)      | The test organization; present when `test_connection` was requested.                                     |
| `connection`           | No       | [Connection](/reference/schemas/#connection)          | The test organization's connection to the hosted test IdP; present when `test_connection` was requested. |
| `test_url`             | No       | string (`format: "uri"`)                              | A one-time test sign-in URL for `connection`; present when `test_connection` was requested.              |
| `test_url_expires_at`  | No       | string (`format: "date-time"`)                        | —                                                                                                        |

## DevInitCreate

No description.

| Property          | Required | Type and constraints     | Description                                                                                                                                                                                                                                                                                                             |
| ----------------- | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri`    | No       | string (`format: "uri"`) | Registered when missing (exact match).                                                                                                                                                                                                                                                                                  |
| `test_connection` | No       | boolean                  | When true, also returns the sandbox's test organization and its SAML connection to the hosted test IdP (created on the first call, then found by the fixed external ID `ohauthcat-test-organization`) and a fresh one-time `test_url` for a test sign-in. Answers `service_unavailable` where no test IdP is available. |

## Directory

No description.

| Property                   | Required | Type and constraints                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `google_oauth_available`   | No       | boolean                                                                                                                                                                                                                          | Present on `google_admin_sdk` directories only. The directory can be connected through the OhAuthCat Google OAuth app (Connect Google): the app is configured on this deployment. When false, Google Workspace cannot be connected on this deployment.                                                                                                                                                 |
| `bamboohr_oauth_available` | No       | boolean                                                                                                                                                                                                                          | Present on `bamboohr` directories only. The directory can be connected through the OhAuthCat BambooHR app (Connect BambooHR): the app is configured on this deployment. When false, BambooHR cannot be connected on this deployment.                                                                                                                                                                   |
| `gusto_oauth_available`    | No       | boolean                                                                                                                                                                                                                          | Present on `gusto` directories only. Gusto HRIS directory sources can be connected in this environment: Gusto is switched on for this environment and OhAuthCat's Gusto OAuth app is configured. When false, connecting, saving credentials, syncing and previewing are refused, while the directory stays readable and deletable. Before any directory exists, read the same flag on the environment. |
| `id`                       | Yes      | [DirectoryId](/reference/schemas/#directoryid)                                                                                                                                                                                   | —                                                                                                                                                                                                                                                                                                                                                                                                      |
| `object`                   | Yes      | string (`const: "directory"`)                                                                                                                                                                                                    | —                                                                                                                                                                                                                                                                                                                                                                                                      |
| `legacy_ids`               | No       | [LegacyIds](/reference/schemas/#legacyids)                                                                                                                                                                                       | IDs of this object in the system it was imported from, by source (e.g. `{"workos":"org_…"}`); absent when it was not imported.                                                                                                                                                                                                                                                                         |
| `organization_id`          | No       | [OrganizationId](/reference/schemas/#organizationid)                                                                                                                                                                             | —                                                                                                                                                                                                                                                                                                                                                                                                      |
| `name`                     | No       | string                                                                                                                                                                                                                           | —                                                                                                                                                                                                                                                                                                                                                                                                      |
| `provider`                 | No       | string (`enum: ["okta","entra","google","onelogin","jumpcloud","generic","cyberark","pingfederate","rippling","sailpoint","csv","bamboohr","rippling_hris","google_admin_sdk","sftp_csv","workday","hibob","personio","gusto"]`) | —                                                                                                                                                                                                                                                                                                                                                                                                      |
| `state`                    | Yes      | string (`enum: ["awaiting_first_request","awaiting_first_sync","active","inactive"]`)                                                                                                                                            | `awaiting_first_request`: a SCIM directory that has had no authenticated SCIM request yet. `awaiting_first_sync`: a directory synced from a pulled source (an HRIS, Google Workspace, SFTP) or from CSV uploads that has had no successful sync or import yet. Either becomes `active` on its first success.                                                                                           |
| `scim_base_url`            | No       | string (`format: "uri"`)                                                                                                                                                                                                         | The SCIM endpoint; present on SCIM directories only. Directories synced from a pulled source or CSV have none.                                                                                                                                                                                                                                                                                         |
| `created_at`               | Yes      | [Timestamp](/reference/schemas/#timestamp)                                                                                                                                                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                      |

## DirectoryCreate

No description.

| Property       | Required | Type and constraints                                                                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                   |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid)                                                                                                                                                                             | —                                                                                                                                                                                                                                                                                                             |
| `name`         | No       | string                                                                                                                                                                                                                           | —                                                                                                                                                                                                                                                                                                             |
| `provider`     | Yes      | string (`enum: ["okta","entra","google","onelogin","jumpcloud","generic","cyberark","pingfederate","rippling","sailpoint","csv","bamboohr","rippling_hris","google_admin_sdk","sftp_csv","workday","hibob","personio","gusto"]`) | A directory provider of GET /v1/providers. `google` is Google Workspace SCIM push from Google's custom SCIM profiles beta: people only, no groups, and only Workspaces admitted to Google's beta. `google_admin_sdk` (Connect Google) is the recommended Google Workspace source and syncs people and groups. |

## DirectoryCredentials

No description.

| Property                    | Required | Type and constraints                       | Description                                                                                                                                                                                                                                   |
| --------------------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `directory`                 | No       | [Directory](/reference/schemas/#directory) | —                                                                                                                                                                                                                                             |
| `scim_base_url`             | No       | string (`format: "uri"`)                   | The SCIM endpoint; present for SCIM directories only. A directory synced from a pulled source (an HRIS, Google Workspace, SFTP) or from CSV uploads gets no SCIM credentials and refuses every SCIM request with `directory_source_mismatch`. |
| `token`                     | No       | string                                     | Shown once; stored hashed. Present for SCIM directories only (see `scim_base_url`).                                                                                                                                                           |
| `previous_token_expires_at` | No       | string or null (`format: "date-time"`)     | Set on rotation: the old token stays valid for 1 h.                                                                                                                                                                                           |

## DirectoryGroup

No description.

| Property       | Required | Type and constraints                                     | Description                                                                                                                    |
| -------------- | -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`           | Yes      | [DirectoryGroupId](/reference/schemas/#directorygroupid) | —                                                                                                                              |
| `object`       | Yes      | string (`const: "directory_group"`)                      | —                                                                                                                              |
| `legacy_ids`   | No       | [LegacyIds](/reference/schemas/#legacyids)               | IDs of this object in the system it was imported from, by source (e.g. `{"workos":"org_…"}`); absent when it was not imported. |
| `directory_id` | Yes      | [DirectoryId](/reference/schemas/#directoryid)           | —                                                                                                                              |
| `idp_id`       | No       | string                                                   | —                                                                                                                              |
| `name`         | Yes      | string                                                   | —                                                                                                                              |
| `created_at`   | No       | [Timestamp](/reference/schemas/#timestamp)               | —                                                                                                                              |
| `updated_at`   | No       | [Timestamp](/reference/schemas/#timestamp)               | —                                                                                                                              |

## DirectoryGroupId

No description.

string (`pattern: "^dgrp_[0-9A-HJKMNP-TV-Z]{26}$"`)

## DirectoryGroupList

No description.

| Property      | Required | Type and constraints                                          | Description |
| ------------- | -------- | ------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                      | —           |
| `data`        | Yes      | Array of [DirectoryGroup](/reference/schemas/#directorygroup) | —           |
| `has_more`    | Yes      | boolean                                                       | —           |
| `next_cursor` | Yes      | string or null                                                | —           |

## DirectoryId

No description.

string (`pattern: "^dir_[0-9A-HJKMNP-TV-Z]{26}$"`)

## DirectoryList

No description.

| Property      | Required | Type and constraints                                | Description |
| ------------- | -------- | --------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                            | —           |
| `data`        | Yes      | Array of [Directory](/reference/schemas/#directory) | —           |
| `has_more`    | Yes      | boolean                                             | —           |
| `next_cursor` | Yes      | string or null                                      | —           |

## DirectorySource

No description.

| Property                | Required | Type and constraints                                                                                             | Description                                                                                                      |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `object`                | Yes      | string (`const: "directory_source"`)                                                                             | —                                                                                                                |
| `directory_id`          | Yes      | [DirectoryId](/reference/schemas/#directoryid)                                                                   | —                                                                                                                |
| `kind`                  | Yes      | string (`enum: ["bamboohr","rippling_hris","google_admin_sdk","sftp_csv","workday","hibob","personio","gusto"]`) | —                                                                                                                |
| `next_sync_at`          | Yes      | [Timestamp](/reference/schemas/#timestamp)                                                                       | —                                                                                                                |
| `last_synced_at`        | No       | [Timestamp](/reference/schemas/#timestamp)                                                                       | —                                                                                                                |
| `last_error`            | No       | string                                                                                                           | Error code of the last failed poll; absent after a success.                                                      |
| `failures`              | Yes      | integer                                                                                                          | —                                                                                                                |
| `sync_interval_minutes` | No       | integer                                                                                                          | Minutes between successful polls (default 5).                                                                    |
| `last_result`           | No       | object (`additionalProperties: {"type":"integer"}`)                                                              | Counts of the last successful poll, including `users_skipped` (people the source returned that were not synced). |
| `last_skipped`          | No       | Array of [DirectorySyncSkipped](/reference/schemas/#directorysyncskipped)                                        | Up to 20 of the people the last successful poll did not sync, with the reason; absent when it skipped none.      |

## DirectorySourceCredentials

No description.

| Property                | Required | Type and constraints                                                 | Description                                                             |
| ----------------------- | -------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `credentials`           | Yes      | object (`additionalProperties: {"type":"string","maxLength":12000}`) | The source's credentials (see the operation); never returned or logged. |
| `sync_interval_minutes` | No       | integer (`minimum: 5`; `maximum: 1440`)                              | Minutes between successful polls; default 5.                            |

## DirectorySourceOAuth

No description.

| Property       | Required | Type and constraints                                                | Description |
| -------------- | -------- | ------------------------------------------------------------------- | ----------- |
| `object`       | Yes      | string (`const: "directory_source_oauth"`)                          | —           |
| `directory_id` | Yes      | [DirectoryId](/reference/schemas/#directoryid)                      | —           |
| `provider`     | Yes      | string (`enum: ["gusto","bamboohr","google"]`)                      | —           |
| `status`       | Yes      | string (`enum: ["pending_company","active","credentials_invalid"]`) | —           |
| `companies`    | Yes      | Array of object                                                     | —           |
| `company_id`   | No       | string                                                              | —           |
| `created_at`   | Yes      | [Timestamp](/reference/schemas/#timestamp)                          | —           |
| `updated_at`   | Yes      | [Timestamp](/reference/schemas/#timestamp)                          | —           |

## DirectorySourceOAuthCompanyRequest

No description.

| Property     | Required | Type and constraints                     | Description |
| ------------ | -------- | ---------------------------------------- | ----------- |
| `company_id` | Yes      | string (`minLength: 1`; `maxLength: 64`) | —           |

## DirectorySourceOAuthStart

No description.

| Property            | Required | Type and constraints                             | Description |
| ------------------- | -------- | ------------------------------------------------ | ----------- |
| `object`            | Yes      | string (`const: "directory_source_oauth_start"`) | —           |
| `directory_id`      | Yes      | [DirectoryId](/reference/schemas/#directoryid)   | —           |
| `provider`          | Yes      | string (`enum: ["gusto","bamboohr","google"]`)   | —           |
| `authorization_url` | Yes      | string (`format: "uri"`)                         | —           |
| `expires_at`        | Yes      | [Timestamp](/reference/schemas/#timestamp)       | —           |

## DirectorySourceOAuthStartRequest

No description.

| Property     | Required | Type and constraints                                                                                       | Description                                                                                                                                                                                                                                |
| ------------ | -------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `return_url` | Yes      | string (`format: "uri"`; `maxLength: 2000`)                                                                | Where the callback sends the browser afterwards: an https URL (http only for localhost in local deployments), without a fragment.                                                                                                          |
| `subdomain`  | No       | string (`pattern: "^[a-z0-9][a-z0-9-]{0,62}$"`)                                                            | Required for a `bamboohr` directory: the company's BambooHR domain, the part before `.bamboohr.com`. BambooHR's sign-in page is on that domain. Ignored for `gusto` and `google_admin_sdk`.                                                |
| `domain`     | No       | string (`maxLength: 253`; `pattern: "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$"`) | Optional for a `google_admin_sdk` directory: the Google Workspace domain, sent to Google only as the `hd` sign-in hint. Never trusted for identity: the Workspace domain is taken from the verified ID token. Ignored for other providers. |

## DirectorySourceProvider

No description.

| Property       | Required | Type and constraints                                             | Description                                                                                                                                                                                                                                                                                             |
| -------------- | -------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | Yes      | string                                                           | The directory `provider` value.                                                                                                                                                                                                                                                                         |
| `name`         | Yes      | string                                                           | —                                                                                                                                                                                                                                                                                                       |
| `portal_idp`   | No       | [PortalIDPId](/reference/schemas/#portalidpid)                   | —                                                                                                                                                                                                                                                                                                       |
| `source`       | Yes      | string (`enum: ["scim","csv","hris","google_admin_sdk","sftp"]`) | `scim`: the IdP pushes SCIM 2.0; `csv`: CSV files uploaded to /v1/directories/{dir}/csv_imports; `hris` and `google_admin_sdk`: polled by OhAuthCat with credentials saved on /v1/directories/{dir}/source; `sftp`: CSV files OhAuthCat reads from the customer's SFTP server, configured the same way. |
| `quirks`       | Yes      | Array of [ProviderQuirk](/reference/schemas/#providerquirk)      | —                                                                                                                                                                                                                                                                                                       |
| `availability` | No       | [ProviderAvailability](/reference/schemas/#provideravailability) | —                                                                                                                                                                                                                                                                                                       |
| `interested`   | No       | boolean                                                          | Only on GET /dashboard/providers and GET /portal/providers, and only for a `coming_soon` source; whether the caller (the dashboard member, or the portal's IT admin) registered interest in it.                                                                                                         |

## DirectorySourceSSHKey

No description.

| Property       | Required | Type and constraints                           | Description                                                    |
| -------------- | -------- | ---------------------------------------------- | -------------------------------------------------------------- |
| `object`       | Yes      | string (`const: "directory_source_ssh_key"`)   | —                                                              |
| `directory_id` | Yes      | [DirectoryId](/reference/schemas/#directoryid) | —                                                              |
| `public_key`   | Yes      | string                                         | The OpenSSH authorized_keys line to install for the SFTP user. |
| `fingerprint`  | Yes      | string                                         | SHA256 fingerprint, as ssh-keygen -l prints it.                |
| `created_at`   | Yes      | [Timestamp](/reference/schemas/#timestamp)     | —                                                              |

## DirectorySourceUpdate

No description.

| Property                | Required | Type and constraints                    | Description                   |
| ----------------------- | -------- | --------------------------------------- | ----------------------------- |
| `sync_interval_minutes` | Yes      | integer (`minimum: 5`; `maximum: 1440`) | The poll interval in minutes. |

## DirectorySyncResult

No description.

| Property         | Required | Type and constraints                                                      | Description                                                                                                             |
| ---------------- | -------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `object`         | Yes      | string (`const: "directory_sync"`)                                        | —                                                                                                                       |
| `directory_id`   | Yes      | [DirectoryId](/reference/schemas/#directoryid)                            | —                                                                                                                       |
| `dry_run`        | Yes      | boolean                                                                   | —                                                                                                                       |
| `users_created`  | Yes      | integer                                                                   | —                                                                                                                       |
| `users_updated`  | Yes      | integer                                                                   | —                                                                                                                       |
| `users_deleted`  | Yes      | integer                                                                   | —                                                                                                                       |
| `groups_created` | Yes      | integer                                                                   | —                                                                                                                       |
| `groups_updated` | Yes      | integer                                                                   | —                                                                                                                       |
| `groups_deleted` | Yes      | integer                                                                   | —                                                                                                                       |
| `users_skipped`  | No       | integer                                                                   | People the source returned that were not synced (see `skipped`). Absent for CSV imports, which refuse bad rows instead. |
| `skipped`        | No       | Array of [DirectorySyncSkipped](/reference/schemas/#directorysyncskipped) | Up to 20 of the people not synced, with the reason.                                                                     |

## DirectorySyncSkipped

No description.

| Property      | Required | Type and constraints                       | Description                                                                                                                              |
| ------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `external_id` | No       | string                                     | The person's ID in the source; absent when the source gave none.                                                                         |
| `name`        | No       | string                                     | The person's display name in the source, when it gave one. Email addresses are never returned.                                           |
| `reason`      | Yes      | string (`enum: ["no_id","no_work_email"]`) | `no_id`: the source gave no ID. `no_work_email`: the person has no work email, so they cannot sign in. Clients must tolerate new values. |

## DirectoryUpdate

No description.

| Property | Required | Type and constraints | Description         |
| -------- | -------- | -------------------- | ------------------- |
| `name`   | No       | string               | "" clears the name. |

## DirectoryUser

No description.

| Property                    | Required | Type and constraints                                                          | Description                                                                                                                                                                                                                                                                                                         |
| --------------------------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `custom_attributes`         | No       | [CustomAttributeValues](/reference/schemas/#customattributevalues)            | —                                                                                                                                                                                                                                                                                                                   |
| `custom_attribute_warnings` | No       | Array of [CustomAttributeWarning](/reference/schemas/#customattributewarning) | Safe cached mapping diagnostics for authorized management and portal use; no source values or provider identifiers. Diagnostic-only changes do not emit user-updated events.                                                                                                                                        |
| `role`                      | No       | string or null (`maxLength: 128`)                                             | Application role from directory evidence. Rule and membership changes propagate through bounded background projection. Authenticated IdP group claims and OIDC email verification are sign-in-only evidence and can produce a different profile role. An absent role on a user-updated event clears the assignment. |
| `id`                        | Yes      | [DirectoryUserId](/reference/schemas/#directoryuserid)                        | —                                                                                                                                                                                                                                                                                                                   |
| `object`                    | Yes      | string (`const: "directory_user"`)                                            | —                                                                                                                                                                                                                                                                                                                   |
| `legacy_ids`                | No       | [LegacyIds](/reference/schemas/#legacyids)                                    | IDs of this object in the system it was imported from, by source (e.g. `{"workos":"org_…"}`); absent when it was not imported.                                                                                                                                                                                      |
| `directory_id`              | Yes      | [DirectoryId](/reference/schemas/#directoryid)                                | —                                                                                                                                                                                                                                                                                                                   |
| `organization_id`           | No       | [OrganizationId](/reference/schemas/#organizationid)                          | —                                                                                                                                                                                                                                                                                                                   |
| `idp_id`                    | No       | string                                                                        | —                                                                                                                                                                                                                                                                                                                   |
| `email`                     | No       | string or null                                                                | —                                                                                                                                                                                                                                                                                                                   |
| `first_name`                | No       | string or null                                                                | —                                                                                                                                                                                                                                                                                                                   |
| `last_name`                 | No       | string or null                                                                | —                                                                                                                                                                                                                                                                                                                   |
| `state`                     | Yes      | string (`enum: ["active","inactive","out_of_domain"]`)                        | `inactive` when the directory deactivated the user (SCIM `active: false`), whatever its email domain; otherwise `out_of_domain` when its email is not on one of the organization's verified domains (or it has none), else `active`.                                                                                |
| `attributes`                | No       | object (`additionalProperties: true`)                                         | —                                                                                                                                                                                                                                                                                                                   |
| `raw_attributes`            | No       | object (`additionalProperties: true`)                                         | —                                                                                                                                                                                                                                                                                                                   |
| `created_at`                | No       | [Timestamp](/reference/schemas/#timestamp)                                    | —                                                                                                                                                                                                                                                                                                                   |
| `updated_at`                | No       | [Timestamp](/reference/schemas/#timestamp)                                    | —                                                                                                                                                                                                                                                                                                                   |

## DirectoryUserId

No description.

string (`pattern: "^dusr_[0-9A-HJKMNP-TV-Z]{26}$"`)

## DirectoryUserList

No description.

| Property      | Required | Type and constraints                                        | Description |
| ------------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                    | —           |
| `data`        | Yes      | Array of [DirectoryUser](/reference/schemas/#directoryuser) | —           |
| `has_more`    | Yes      | boolean                                                     | —           |
| `next_cursor` | Yes      | string or null                                              | —           |

## DnsRecord

No description.

| Property | Required | Type and constraints             | Description |
| -------- | -------- | -------------------------------- | ----------- |
| `type`   | Yes      | string (`enum: ["CNAME","TXT"]`) | —           |
| `name`   | Yes      | string                           | —           |
| `value`  | Yes      | string                           | —           |

## DoctorOutput

No description.

| Property           | Required | Type and constraints | Description                                                                          |
| ------------------ | -------- | -------------------- | ------------------------------------------------------------------------------------ |
| `error_code`       | Yes      | string               | —                                                                                    |
| `idp`              | Yes      | string               | The IdP whose steps are shown (okta, entra, google, onelogin, jumpcloud) or generic. |
| `cause`            | Yes      | string               | —                                                                                    |
| `it_admin_message` | Yes      | string               | —                                                                                    |
| `fix_guide_id`     | Yes      | string               | —                                                                                    |
| `steps`            | Yes      | Array of string      | —                                                                                    |

## Domain

No description.

| Property              | Required | Type and constraints                                     | Description |
| --------------------- | -------- | -------------------------------------------------------- | ----------- |
| `id`                  | Yes      | [DomainId](/reference/schemas/#domainid)                 | —           |
| `object`              | Yes      | string (`const: "domain"`)                               | —           |
| `organization_id`     | No       | [OrganizationId](/reference/schemas/#organizationid)     | —           |
| `domain`              | Yes      | string                                                   | —           |
| `state`               | Yes      | string (`enum: ["pending","verified","record_missing"]`) | —           |
| `include_subdomains`  | No       | boolean                                                  | —           |
| `verification_record` | No       | object                                                   | —           |
| `verified_at`         | No       | string or null (`format: "date-time"`)                   | —           |
| `created_at`          | Yes      | [Timestamp](/reference/schemas/#timestamp)               | —           |

## DomainCreate

No description.

| Property             | Required | Type and constraints                      | Description |
| -------------------- | -------- | ----------------------------------------- | ----------- |
| `domain`             | Yes      | string (`minLength: 1`; `maxLength: 253`) | —           |
| `include_subdomains` | No       | boolean                                   | —           |

## DomainId

No description.

string (`pattern: "^dom_[0-9A-HJKMNP-TV-Z]{26}$"`)

## DomainList

No description.

| Property      | Required | Type and constraints                          | Description |
| ------------- | -------- | --------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                      | —           |
| `data`        | Yes      | Array of [Domain](/reference/schemas/#domain) | —           |
| `has_more`    | Yes      | boolean                                       | —           |
| `next_cursor` | Yes      | string or null                                | —           |

## DomainUpdate

No description.

| Property             | Required | Type and constraints | Description |
| -------------------- | -------- | -------------------- | ----------- |
| `include_subdomains` | Yes      | boolean              | —           |

## EmailEvent

One email OhAuthCat sent for the environment. The recipient is never returned, only its domain.

| Property           | Required | Type and constraints               | Description        |
| ------------------ | -------- | ---------------------------------- | ------------------ |
| `id`               | Yes      | string (`format: "uuid"`)          | —                  |
| `object`           | Yes      | string (`const: "email_event"`)    | —                  |
| `kind`             | Yes      | string                             | The template name. |
| `status`           | Yes      | string (`enum: ["sent","failed"]`) | —                  |
| `provider`         | Yes      | string                             | —                  |
| `recipient_domain` | Yes      | string or null                     | —                  |
| `created_at`       | Yes      | string (`format: "date-time"`)     | —                  |

## EmailEventList

No description.

| Property      | Required | Type and constraints                                  | Description |
| ------------- | -------- | ----------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                              | —           |
| `data`        | Yes      | Array of [EmailEvent](/reference/schemas/#emailevent) | —           |
| `has_more`    | Yes      | boolean                                               | —           |
| `next_cursor` | Yes      | string or null                                        | —           |

## EncryptionKey

No description.

| Property        | Required | Type and constraints                                         | Description                                                                                                                                      |
| --------------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`            | Yes      | [EncryptionKeyId](/reference/schemas/#encryptionkeyid)       | —                                                                                                                                                |
| `object`        | Yes      | string (`enum: ["encryption_key"]`)                          | —                                                                                                                                                |
| `scope`         | Yes      | string (`enum: ["environment","organization"]`)              | —                                                                                                                                                |
| `organization`  | No       | [OrganizationId](/reference/schemas/#organizationid)         | Set for an organization key.                                                                                                                     |
| `version`       | Yes      | integer (`minimum: 1`)                                       | —                                                                                                                                                |
| `provider`      | Yes      | string (`enum: ["aws_kms"]`)                                 | —                                                                                                                                                |
| `key_arn`       | Yes      | string                                                       | —                                                                                                                                                |
| `state`         | Yes      | string (`enum: ["active","enabled","deprecated","revoked"]`) | active wraps new data (one per scope); enabled and deprecated still unwrap what they wrapped; revoked unwraps nothing and its data fails closed. |
| `last_error`    | No       | string                                                       | Why the version was found unusable (for example disabled, access_denied, not_found).                                                             |
| `created_at`    | Yes      | string (`format: "date-time"`)                               | —                                                                                                                                                |
| `validated_at`  | Yes      | string (`format: "date-time"`)                               | —                                                                                                                                                |
| `deprecated_at` | No       | string (`format: "date-time"`)                               | —                                                                                                                                                |
| `revoked_at`    | No       | string (`format: "date-time"`)                               | —                                                                                                                                                |

## EncryptionKeyCreate

No description.

| Property       | Required | Type and constraints                                 | Description                                                          |
| -------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
| `key_arn`      | Yes      | string (`minLength: 20`; `maxLength: 256`)           | Full AWS KMS key ARN (single- or multi-Region); aliases are refused. |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | Register an organization key instead of the environment-wide key.    |

## EncryptionKeyId

No description.

string (`pattern: "^ekey_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EncryptionKeyList

No description.

| Property  | Required | Type and constraints                                                    | Description |
| --------- | -------- | ----------------------------------------------------------------------- | ----------- |
| `object`  | Yes      | string (`enum: ["list"]`)                                               | —           |
| `data`    | Yes      | Array of [EncryptionKey](/reference/schemas/#encryptionkey)             | —           |
| `reseals` | Yes      | Array of [EncryptionKeyReseal](/reference/schemas/#encryptionkeyreseal) | —           |

## EncryptionKeyReseal

No description.

| Property        | Required | Type and constraints                                   | Description                                                                       |
| --------------- | -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `scope`         | Yes      | string (`enum: ["environment","organization"]`)        | —                                                                                 |
| `organization`  | No       | [OrganizationId](/reference/schemas/#organizationid)   | —                                                                                 |
| `target_key`    | Yes      | [EncryptionKeyId](/reference/schemas/#encryptionkeyid) | —                                                                                 |
| `status`        | Yes      | string (`enum: ["pending","done","failed"]`)           | —                                                                                 |
| `rows_resealed` | Yes      | integer (`format: "int64"`)                            | —                                                                                 |
| `enforced`      | Yes      | boolean                                                | Every secret of the scope carries the customer layer; data without it is refused. |
| `last_error`    | No       | string                                                 | —                                                                                 |
| `updated_at`    | Yes      | string (`format: "date-time"`)                         | —                                                                                 |

## EncryptionKeySetup

No description.

| Property               | Required | Type and constraints                      | Description                                                                                   |
| ---------------------- | -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| `object`               | Yes      | string (`enum: ["encryption_key_setup"]`) | —                                                                                             |
| `principal_arn`        | Yes      | string                                    | Our service role to name in the key policy. Empty when BYOK is not configured in this region. |
| `environment`          | Yes      | string                                    | —                                                                                             |
| `scope`                | Yes      | string                                    | —                                                                                             |
| `key_policy_statement` | Yes      | string                                    | JSON of the key policy statement to add to the customer key.                                  |

## EndUser

A user of the developer's app, scoped to one environment.

| Property          | Required | Type and constraints                             | Description |
| ----------------- | -------- | ------------------------------------------------ | ----------- |
| `id`              | Yes      | [EndUserId](/reference/schemas/#enduserid)       | —           |
| `object`          | Yes      | string (`const: "user"`)                         | —           |
| `email`           | Yes      | string (`format: "email"`)                       | —           |
| `email_verified`  | Yes      | boolean                                          | —           |
| `first_name`      | Yes      | string or null                                   | —           |
| `last_name`       | Yes      | string or null                                   | —           |
| `locale`          | Yes      | string or null                                   | —           |
| `external_id`     | Yes      | string or null                                   | —           |
| `metadata`        | Yes      | [Metadata](/reference/schemas/#metadata)         | —           |
| `state`           | Yes      | [EndUserState](/reference/schemas/#enduserstate) | —           |
| `last_sign_in_at` | Yes      | string or null (`format: "date-time"`)           | —           |
| `created_at`      | Yes      | string (`format: "date-time"`)                   | —           |
| `updated_at`      | Yes      | string (`format: "date-time"`)                   | —           |

## EndUserCreate

No description.

| Property         | Required | Type and constraints                      | Description                                                     |
| ---------------- | -------- | ----------------------------------------- | --------------------------------------------------------------- |
| `email`          | Yes      | string (`minLength: 3`; `maxLength: 320`) | —                                                               |
| `email_verified` | No       | boolean                                   | Mark the address verified (only when your app has verified it). |
| `first_name`     | No       | string (`minLength: 1`; `maxLength: 200`) | —                                                               |
| `last_name`      | No       | string (`minLength: 1`; `maxLength: 200`) | —                                                               |
| `locale`         | No       | string (`minLength: 2`; `maxLength: 35`)  | —                                                               |
| `external_id`    | No       | string (`minLength: 1`; `maxLength: 256`) | —                                                               |
| `metadata`       | No       | [Metadata](/reference/schemas/#metadata)  | —                                                               |

## EndUserFactor

No description.

| Property       | Required | Type and constraints                                   | Description |
| -------------- | -------- | ------------------------------------------------------ | ----------- |
| `id`           | Yes      | [EndUserFactorId](/reference/schemas/#enduserfactorid) | —           |
| `object`       | Yes      | string (`const: "factor"`)                             | —           |
| `type`         | Yes      | string (`enum: ["passkey","totp"]`)                    | —           |
| `name`         | Yes      | string or null                                         | —           |
| `confirmed`    | Yes      | boolean                                                | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                         | —           |
| `last_used_at` | Yes      | string or null (`format: "date-time"`)                 | —           |

## EndUserFactorId

No description.

string (`pattern: "^ucred_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EndUserFactorList

No description.

| Property | Required | Type and constraints                                        | Description |
| -------- | -------- | ----------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                    | —           |
| `data`   | Yes      | Array of [EndUserFactor](/reference/schemas/#enduserfactor) | —           |

## EndUserId

No description.

string (`pattern: "^usr_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EndUserIdentity

No description.

| Property       | Required | Type and constraints           | Description |
| -------------- | -------- | ------------------------------ | ----------- |
| `object`       | Yes      | string (`const: "identity"`)   | —           |
| `provider`     | Yes      | string                         | —           |
| `subject`      | Yes      | string                         | —           |
| `email`        | Yes      | string or null                 | —           |
| `created_at`   | Yes      | string (`format: "date-time"`) | —           |
| `last_used_at` | Yes      | string (`format: "date-time"`) | —           |

## EndUserIdentityList

No description.

| Property | Required | Type and constraints                                            | Description |
| -------- | -------- | --------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                        | —           |
| `data`   | Yes      | Array of [EndUserIdentity](/reference/schemas/#enduseridentity) | —           |

## EndUserInvite

No description.

| Property       | Required | Type and constraints                                         | Description |
| -------------- | -------- | ------------------------------------------------------------ | ----------- |
| `id`           | Yes      | [EndUserInviteId](/reference/schemas/#enduserinviteid)       | —           |
| `object`       | Yes      | string (`const: "invite"`)                                   | —           |
| `email`        | Yes      | string                                                       | —           |
| `organization` | Yes      | [See the full composed schema](/spec/openapi-v1.yaml)        | —           |
| `role`         | Yes      | [See the full composed schema](/spec/openapi-v1.yaml)        | —           |
| `state`        | Yes      | [EndUserInviteState](/reference/schemas/#enduserinvitestate) | —           |
| `expires_at`   | Yes      | string (`format: "date-time"`)                               | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                               | —           |

## EndUserInviteCreate

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `email`        | Yes      | string (`minLength: 3`; `maxLength: 320`)            | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `role`         | No       | [MembershipRole](/reference/schemas/#membershiprole) | —           |
| `inviter`      | No       | [EndUserId](/reference/schemas/#enduserid)           | —           |

## EndUserInviteCreated

No description.

[See the full composed schema](/spec/openapi-v1.yaml)

## EndUserInviteId

No description.

string (`pattern: "^uinv_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EndUserInviteList

No description.

| Property      | Required | Type and constraints                                        | Description |
| ------------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                    | —           |
| `data`        | Yes      | Array of [EndUserInvite](/reference/schemas/#enduserinvite) | —           |
| `has_more`    | Yes      | boolean                                                     | —           |
| `next_cursor` | Yes      | string or null                                              | —           |

## EndUserInviteState

No description.

string (`enum: ["pending","accepted","revoked","expired"]`)

## EndUserList

No description.

| Property      | Required | Type and constraints                            | Description |
| ------------- | -------- | ----------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                        | —           |
| `data`        | Yes      | Array of [EndUser](/reference/schemas/#enduser) | —           |
| `has_more`    | Yes      | boolean                                         | —           |
| `next_cursor` | Yes      | string or null                                  | —           |

## EndUserPasskeyAuthenticate

No description.

| Property     | Required | Type and constraints                  | Description                                                    |
| ------------ | -------- | ------------------------------------- | -------------------------------------------------------------- |
| `credential` | Yes      | object (`additionalProperties: true`) | —                                                              |
| `session`    | No       | boolean                               | Also create a session and return its tokens (needs client_id). |
| `client_id`  | No       | string (`maxLength: 256`)             | The publishable key the tokens are issued to (their audience). |

## EndUserPasskeyAuthentication

No description.

| Property        | Required | Type and constraints                       | Description                |
| --------------- | -------- | ------------------------------------------ | -------------------------- |
| `object`        | Yes      | string (`const: "passkey_authentication"`) | —                          |
| `user`          | Yes      | [EndUser](/reference/schemas/#enduser)     | —                          |
| `session_id`    | No       | string                                     | Present with session true. |
| `access_token`  | No       | string                                     | —                          |
| `refresh_token` | No       | string                                     | —                          |
| `id_token`      | No       | string                                     | —                          |
| `token_type`    | No       | string (`const: "Bearer"`)                 | —                          |
| `expires_in`    | No       | integer                                    | —                          |

## EndUserPasskeyRegister

No description.

| Property     | Required | Type and constraints                      | Description |
| ------------ | -------- | ----------------------------------------- | ----------- |
| `credential` | Yes      | object (`additionalProperties: true`)     | —           |
| `name`       | No       | string (`minLength: 1`; `maxLength: 100`) | —           |

## EndUserPasskeyUpdate

No description.

| Property | Required | Type and constraints                     | Description |
| -------- | -------- | ---------------------------------------- | ----------- |
| `name`   | Yes      | string (`minLength: 1`; `maxLength: 64`) | —           |

## EndUserPasswordSet

No description.

| Property          | Required | Type and constraints                       | Description                                                                                                                                                                                                                                         |
| ----------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `password`        | Yes      | string (`minLength: 1`; `maxLength: 1024`) | —                                                                                                                                                                                                                                                   |
| `revoke_sessions` | No       | boolean (`default: true`)                  | Sign the user out everywhere (D192): end every hosted sign-in session of the user and delete the refresh tokens of its OAuth grants, in the same transaction, audited as user.signed_out with the counts. false keeps them signed in. Default true. |

## EndUserSession

No description.

| Property              | Required | Type and constraints                                     | Description |
| --------------------- | -------- | -------------------------------------------------------- | ----------- |
| `id`                  | Yes      | [EndUserSessionId](/reference/schemas/#endusersessionid) | —           |
| `object`              | Yes      | string (`const: "session"`)                              | —           |
| `user`                | Yes      | [EndUserId](/reference/schemas/#enduserid)               | —           |
| `organization`        | Yes      | string or null                                           | —           |
| `auth_methods`        | Yes      | Array of string                                          | —           |
| `mfa`                 | Yes      | boolean                                                  | —           |
| `ip`                  | Yes      | string or null                                           | —           |
| `user_agent`          | Yes      | string or null                                           | —           |
| `created_at`          | Yes      | string (`format: "date-time"`)                           | —           |
| `last_seen_at`        | Yes      | string (`format: "date-time"`)                           | —           |
| `idle_expires_at`     | Yes      | string (`format: "date-time"`)                           | —           |
| `absolute_expires_at` | Yes      | string (`format: "date-time"`)                           | —           |

## EndUserSessionId

No description.

string (`pattern: "^uses_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EndUserSessionList

No description.

| Property | Required | Type and constraints                                          | Description |
| -------- | -------- | ------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                      | —           |
| `data`   | Yes      | Array of [EndUserSession](/reference/schemas/#endusersession) | —           |

## EndUserState

No description.

string (`enum: ["active","blocked"]`)

## EndUserUpdate

No description.

| Property         | Required | Type and constraints                             | Description |
| ---------------- | -------- | ------------------------------------------------ | ----------- |
| `email_verified` | No       | boolean                                          | —           |
| `first_name`     | No       | string or null (`maxLength: 200`)                | —           |
| `last_name`      | No       | string or null (`maxLength: 200`)                | —           |
| `locale`         | No       | string or null (`maxLength: 35`)                 | —           |
| `external_id`    | No       | string or null (`maxLength: 256`)                | —           |
| `metadata`       | No       | [Metadata](/reference/schemas/#metadata)         | —           |
| `state`          | No       | [EndUserState](/reference/schemas/#enduserstate) | —           |

## Environment

No description.

| Property                   | Required | Type and constraints                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | Yes      | [EnvironmentId](/reference/schemas/#environmentid)                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `object`                   | Yes      | string (`const: "environment"`)                                                                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `project`                  | No       | [ProjectId](/reference/schemas/#projectid)                                                               | The environment's project.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `name`                     | No       | string                                                                                                   | Free-form display name chosen by the developer (e.g. Staging, EU production). The type, not the name, decides sandbox or production behaviour, and several environments of one type may share a project.                                                                                                                                                                                                                                        |
| `type`                     | Yes      | string (`enum: ["sandbox","production"]`)                                                                | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `consent_screen_default`   | No       | string (`enum: ["on","off"]`)                                                                            | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sign_in_failed_events`    | No       | boolean                                                                                                  | When true, refused sign-ins also emit `sso.sign_in.failed` (high volume; no email or profile ID). Off by default.                                                                                                                                                                                                                                                                                                                               |
| `gusto_oauth_available`    | No       | boolean                                                                                                  | Gusto HRIS directory sources can be connected in this environment: Gusto is switched on for this environment and OhAuthCat's Gusto OAuth app is configured. The same value as `gusto_oauth_available` on a directory, available before any directory exists. When false, hide Gusto when creating a directory.                                                                                                                                  |
| `bamboohr_oauth_available` | No       | boolean                                                                                                  | BambooHR directories can be connected through the OhAuthCat BambooHR app (Connect BambooHR) in this environment. When false, hide BambooHR: it has no other connection method.                                                                                                                                                                                                                                                                  |
| `google_oauth_available`   | No       | boolean                                                                                                  | Google Workspace (`google_admin_sdk`) directories can be connected through the OhAuthCat Google OAuth app (Connect Google) in this environment. When false, hide Google Workspace: it has no other connection method.                                                                                                                                                                                                                           |
| `compat_workos_enabled`    | No       | boolean (`default: false`)                                                                               | Opt in to the confined WorkOS SSO compatibility routes. Off by default; the deployment kill switch must also allow compatibility. Native SSO still requires caller PKCE. Usage feeds the separately managed compatibility support lifecycle.                                                                                                                                                                                                    |
| `version_pin`              | Yes      | string (`pattern: "^1\\.[0-9]+$"`)                                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `home_region`              | No       | string                                                                                                   | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `portal_success_urls`      | No       | object (`additionalProperties: {"type":"string","format":"uri"}`)                                        | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disabled_notices`         | No       | Array of string (`enum: ["cert_expiry","connection_error","domain_record_missing","scim_auth_failure"]`) | Customer-facing notices not mailed to the organizations' IT contacts (the environment's owners and admins still get them). Empty by default.                                                                                                                                                                                                                                                                                                    |
| `portal_logo_url`          | No       | string or null (`format: "uri"`; `maxLength: 2048`)                                                      | Where the setup portal's logo links (https). "" clears it.                                                                                                                                                                                                                                                                                                                                                                                      |
| `portal_embed_origins`     | No       | Array of string (`maxLength: 255`; `pattern: "^https://[^/?#]+$"`)                                       | The https origins (scheme and host, optional port; no path) allowed to show the setup portal in an iframe. Empty (the default) keeps embedding off. While it is set, new portal sessions use a partitioned third-party cookie (`SameSite=None; Secure; Partitioned`) so they work inside the iframe, and the portal's edge sends a `Content-Security-Policy` `frame-ancestors` directive with these origins. An empty list turns embedding off. |
| `support_email`            | No       | string or null (`maxLength: 320`)                                                                        | Customer support address shown in the setup portal and used as the reply-to of IT-contact mail. "" clears it.                                                                                                                                                                                                                                                                                                                                   |
| `sign_ins_disabled`        | No       | boolean                                                                                                  | The environment kill switch (D114) is on, so sign-ins and SCIM are refused. Returned to every dashboard member in the environments list; the reason is only in the owner/admin kill switch route.                                                                                                                                                                                                                                               |
| `sign_ins_disabled_at`     | No       | [Timestamp](/reference/schemas/#timestamp)                                                               | When sign-ins were switched off; present only while `sign_ins_disabled` is true.                                                                                                                                                                                                                                                                                                                                                                |
| `sign_ins_disabled_by`     | No       | string (`enum: ["customer","staff"]`)                                                                    | Who switched sign-ins off, `customer` (an owner or admin of this account) or `staff` (OhAuthCat support); present only while `sign_ins_disabled` is true.                                                                                                                                                                                                                                                                                       |
| `residency`                | No       | [EnvironmentResidency](/reference/schemas/#environmentresidency)                                         | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |

## EnvironmentId

No description.

string (`pattern: "^env_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EnvironmentResidency

Where the environment's data is stored. Personal data stays in the home region; global records carry no personal data.

| Property       | Required | Type and constraints                                                  | Description |
| -------------- | -------- | --------------------------------------------------------------------- | ----------- |
| `region`       | Yes      | [ResidencyRegion](/reference/schemas/#residencyregion)                | —           |
| `data_classes` | Yes      | Array of [ResidencyPlacement](/reference/schemas/#residencyplacement) | —           |

## EnvironmentSigninHost

No description.

| Property              | Required | Type and constraints                                   | Description                                                                                                  |
| --------------------- | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `object`              | Yes      | string (`enum: ["environment_signin_host"]`)           | —                                                                                                            |
| `hostname`            | Yes      | string or null                                         | The active custom signin hostname; null when the environment uses `default_hostname`.                        |
| `default_hostname`    | Yes      | string                                                 | The platform sign-in host, `signin.&lt;domain&gt;`.                                                          |
| `rp_id`               | Yes      | string                                                 | The WebAuthn relying party ID new end-user passkeys bind to.                                                 |
| `rp_id_scope`         | Yes      | [SigninRPIDScope](/reference/schemas/#signinrpidscope) | —                                                                                                            |
| `passkeys_not_usable` | Yes      | integer (`minimum: 0`)                                 | End-user passkeys of the environment that do not work on this host (created under another relying party ID). |
| `updated_at`          | No       | string (`format: "date-time"`)                         | —                                                                                                            |

## EnvironmentSigninHostUpdate

No description.

| Property      | Required | Type and constraints                                   | Description                                                                                                 |
| ------------- | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `hostname`    | Yes      | string or null (`maxLength: 253`)                      | A verified signin custom hostname of this environment, or null for `signin.&lt;domain&gt;`.                 |
| `rp_id_scope` | No       | [SigninRPIDScope](/reference/schemas/#signinrpidscope) | —                                                                                                           |
| `confirm`     | Yes      | string (`maxLength: 253`)                              | The new host typed by the user; must equal `hostname` (or `signin.&lt;domain&gt;` when `hostname` is null). |

## EnvironmentUpdate

No description.

| Property                 | Required | Type and constraints                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `consent_screen_default` | No       | string (`enum: ["on","off"]`)                                                                            | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sign_in_failed_events`  | No       | boolean                                                                                                  | Opt in to `sso.sign_in.failed` for refused sign-ins.                                                                                                                                                                                                                                                                                                                                                                                            |
| `compat_workos_enabled`  | No       | boolean                                                                                                  | Enable or disable WorkOS SSO compatibility for this environment. It remains unavailable when the deployment kill switch is off; native caller PKCE is unchanged.                                                                                                                                                                                                                                                                                |
| `version_pin`            | No       | string (`pattern: "^1\\.[0-9]+$"`)                                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `portal_success_urls`    | No       | object (`additionalProperties: {"type":"string","format":"uri"}`)                                        | —                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `disabled_notices`       | No       | Array of string (`enum: ["cert_expiry","connection_error","domain_record_missing","scim_auth_failure"]`) | Customer-facing notices not mailed to the organizations' IT contacts (the environment's owners and admins still get them). Empty by default.                                                                                                                                                                                                                                                                                                    |
| `portal_logo_url`        | No       | string or null (`format: "uri"`; `maxLength: 2048`)                                                      | Where the setup portal's logo links (https). "" clears it.                                                                                                                                                                                                                                                                                                                                                                                      |
| `portal_embed_origins`   | No       | Array of string (`maxLength: 255`; `pattern: "^https://[^/?#]+$"`)                                       | The https origins (scheme and host, optional port; no path) allowed to show the setup portal in an iframe. Empty (the default) keeps embedding off. While it is set, new portal sessions use a partitioned third-party cookie (`SameSite=None; Secure; Partitioned`) so they work inside the iframe, and the portal's edge sends a `Content-Security-Policy` `frame-ancestors` directive with these origins. An empty list turns embedding off. |
| `support_email`          | No       | string or null (`maxLength: 320`)                                                                        | Customer support address shown in the setup portal and used as the reply-to of IT-contact mail. "" clears it.                                                                                                                                                                                                                                                                                                                                   |

## Error

No description.

| Property | Required | Type and constraints                       | Description |
| -------- | -------- | ------------------------------------------ | ----------- |
| `error`  | Yes      | [ErrorBody](/reference/schemas/#errorbody) | —           |

## ErrorBody

No description.

| Property     | Required | Type and constraints                                                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | Yes      | string (`enum: ["invalid_request","authentication","permission","not_found","conflict","rate_limited","idp_error","unavailable","internal"]`) | —                                                                                                                                                                                                                                                                                                                                                                                      |
| `code`       | Yes      | string (`pattern: "^[a-z][a-z0-9_]*$"`)                                                                                                       | Stable error code from the catalogue in internal/platform/errcodes/catalogue.yaml (handbook doc 27). Codes are never renamed or reused.                                                                                                                                                                                                                                                |
| `message`    | Yes      | string                                                                                                                                        | —                                                                                                                                                                                                                                                                                                                                                                                      |
| `param`      | No       | string or null                                                                                                                                | —                                                                                                                                                                                                                                                                                                                                                                                      |
| `doc_url`    | Yes      | string (`format: "uri"`)                                                                                                                      | `https://docs.ohauthcat.com/errors/<code>`                                                                                                                                                                                                                                                                                                                                             |
| `request_id` | Yes      | [TraceRequestId](/reference/schemas/#tracerequestid)                                                                                          | —                                                                                                                                                                                                                                                                                                                                                                                      |
| `details`    | No       | Array of [ErrorDetail](/reference/schemas/#errordetail)                                                                                       | Structured problems behind the error, when the code has them. `directory_csv_invalid`, one item per row problem (at most 20); `password_invalid` for a password that lacks a required character type, one item per missing type (`row` 0, `column` `password`, `problem` `missing_uppercase`, `missing_lowercase`, `missing_number` or `missing_symbol`). Absent for every other code. |

## ErrorDetail

No description.

| Property  | Required | Type and constraints   | Description                                                                 |
| --------- | -------- | ---------------------- | --------------------------------------------------------------------------- |
| `row`     | Yes      | integer (`minimum: 0`) | 1-based row counting the header line; 0 for the file as a whole.            |
| `column`  | No       | string or null         | The CSV column or request field, or null when the problem is not about one. |
| `problem` | Yes      | string                 | What is wrong, in plain words.                                              |

## Event

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `id`           | Yes      | [EventId](/reference/schemas/#eventid)               | —           |
| `object`       | Yes      | string (`const: "event"`)                            | —           |
| `type`         | Yes      | string                                               | —           |
| `created_at`   | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —           |
| `environment`  | Yes      | [EnvironmentId](/reference/schemas/#environmentid)   | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `directory`    | No       | [DirectoryId](/reference/schemas/#directoryid)       | —           |
| `sequence`     | No       | integer                                              | —           |
| `api_version`  | Yes      | string                                               | —           |
| `data`         | Yes      | object (`additionalProperties: true`)                | —           |

## EventId

No description.

string (`pattern: "^evt_[0-9A-HJKMNP-TV-Z]{26}$"`)

## EventList

No description.

| Property      | Required | Type and constraints                        | Description |
| ------------- | -------- | ------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                    | —           |
| `data`        | Yes      | Array of [Event](/reference/schemas/#event) | —           |
| `has_more`    | Yes      | boolean                                     | —           |
| `next_cursor` | Yes      | string or null                              | —           |

## Export

No description.

| Property             | Required | Type and constraints                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | -------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | Yes      | [ExportId](/reference/schemas/#exportid)                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `object`             | Yes      | string (`const: "export"`)                                | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `organization`       | No       | string or null                                            | The exported organization; null for the whole environment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `secrets_to_reenter` | No       | Array of [ExportSecret](/reference/schemas/#exportsecret) | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `failure_reason`     | No       | string or null                                            | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `created_at`         | No       | string (`format: "date-time"`)                            | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `state`              | Yes      | string (`enum: ["pending","ready","failed"]`)             | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `download_url`       | No       | string or null (`format: "uri"`)                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `expires_at`         | No       | string or null (`format: "date-time"`)                    | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `bundles`            | No       | Array of [ExportBundle](/reference/schemas/#exportbundle) | The export's bundles once it is ready. An export within the bundle limits has one bundle, the same file as `download_url`. An environment export above them (more than 500 organizations, 100 000 directory users or profiles, or a 16 MiB document) is split into one bundle per organization, each importable on its own; `download_url` is then absent. An organization that alone exceeds a limit gets a `failed` bundle with `failure_reason` while the others stay `ready`; the export fails only when every bundle fails. |

## ExportBundle

No description.

| Property         | Required | Type and constraints                   | Description                                                                         |
| ---------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
| `organization`   | No       | string or null                         | The organization in this bundle; null for a single bundle of the whole environment. |
| `state`          | Yes      | string (`enum: ["ready","failed"]`)    | —                                                                                   |
| `size`           | Yes      | integer                                | The bundle's size in bytes (0 when failed).                                         |
| `download_url`   | No       | string or null (`format: "uri"`)       | Signed for each request, like the export's `download_url`.                          |
| `expires_at`     | No       | string or null (`format: "date-time"`) | —                                                                                   |
| `failure_reason` | No       | string or null                         | —                                                                                   |

## ExportCreate

No description.

| Property       | Required | Type and constraints                                 | Description                                                    |
| -------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | Export only this organization (default the whole environment). |

## ExportId

No description.

string (`pattern: "^exp_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ExportSecret

A secret the bundle leaves out, to re-enter after importing it.

| Property | Required | Type and constraints                                                  | Description                                                     |
| -------- | -------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| `kind`   | Yes      | string (`enum: ["oidc_client_secret","scim_token","sp_private_key"]`) | —                                                               |
| `id`     | Yes      | string                                                                | The connection, directory or environment the secret belongs to. |

## FeatureFlag

No description.

| Property      | Required | Type and constraints                                                  | Description |
| ------------- | -------- | --------------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["feature_flag"]`)                                     | —           |
| `id`          | Yes      | [FeatureFlagId](/reference/schemas/#featureflagid)                    | —           |
| `key`         | Yes      | string                                                                | —           |
| `name`        | Yes      | string                                                                | —           |
| `description` | No       | string                                                                | —           |
| `kind`        | Yes      | string (`enum: ["boolean","multivariate"]`)                           | —           |
| `enabled`     | Yes      | boolean                                                               | —           |
| `variants`    | Yes      | Array of [FeatureFlagVariant](/reference/schemas/#featureflagvariant) | —           |
| `off_variant` | Yes      | string                                                                | —           |
| `rules`       | Yes      | Array of [FeatureFlagRule](/reference/schemas/#featureflagrule)       | —           |
| `fallthrough` | Yes      | [FeatureFlagServe](/reference/schemas/#featureflagserve)              | —           |
| `revision`    | Yes      | integer                                                               | —           |
| `created_at`  | Yes      | [Timestamp](/reference/schemas/#timestamp)                            | —           |
| `updated_at`  | Yes      | [Timestamp](/reference/schemas/#timestamp)                            | —           |

## FeatureFlagBulkEvaluateRequest

No description.

| Property  | Required | Type and constraints                                         | Description |
| --------- | -------- | ------------------------------------------------------------ | ----------- |
| `keys`    | No       | Array of string (`maxLength: 128`)                           | —           |
| `context` | No       | [FeatureFlagContext](/reference/schemas/#featureflagcontext) | —           |

## FeatureFlagCondition

No description.

| Property    | Required | Type and constraints                                                                             | Description                                            |
| ----------- | -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `attribute` | Yes      | string (`pattern: "^[A-Za-z0-9_.-]{1,64}$"`)                                                     | organization_id, user_id, or a context attribute name. |
| `operator`  | Yes      | string (`enum: ["in","not_in","contains","starts_with","ends_with","greater_than","less_than"]`) | —                                                      |
| `values`    | Yes      | Array of string (`maxLength: 256`)                                                               | —                                                      |

## FeatureFlagContext

No description.

| Property          | Required | Type and constraints                                               | Description |
| ----------------- | -------- | ------------------------------------------------------------------ | ----------- |
| `organization_id` | No       | string (`maxLength: 256`)                                          | —           |
| `user_id`         | No       | string (`maxLength: 256`)                                          | —           |
| `attributes`      | No       | object (`additionalProperties: {"type":"string","maxLength":256}`) | —           |

## FeatureFlagCreate

No description.

| Property      | Required | Type and constraints                                                  | Description                                                             |
| ------------- | -------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `key`         | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,127}$"`)                    | —                                                                       |
| `name`        | Yes      | string (`minLength: 1`; `maxLength: 200`)                             | —                                                                       |
| `description` | No       | string (`maxLength: 2000`)                                            | —                                                                       |
| `kind`        | Yes      | string (`enum: ["boolean","multivariate"]`)                           | —                                                                       |
| `enabled`     | No       | boolean                                                               | Defaults to false.                                                      |
| `variants`    | No       | Array of [FeatureFlagVariant](/reference/schemas/#featureflagvariant) | —                                                                       |
| `off_variant` | No       | string                                                                | Defaults to `false` for a boolean flag and the first variant otherwise. |
| `rules`       | No       | Array of [FeatureFlagRule](/reference/schemas/#featureflagrule)       | —                                                                       |
| `fallthrough` | No       | [FeatureFlagServe](/reference/schemas/#featureflagserve)              | —                                                                       |

## FeatureFlagEvaluateRequest

No description.

| Property  | Required | Type and constraints                                         | Description |
| --------- | -------- | ------------------------------------------------------------ | ----------- |
| `key`     | Yes      | string (`maxLength: 128`)                                    | —           |
| `context` | No       | [FeatureFlagContext](/reference/schemas/#featureflagcontext) | —           |

## FeatureFlagEvaluation

No description.

| Property  | Required | Type and constraints                         | Description                                        |
| --------- | -------- | -------------------------------------------- | -------------------------------------------------- |
| `object`  | Yes      | string (`enum: ["feature_flag_evaluation"]`) | —                                                  |
| `key`     | Yes      | string                                       | —                                                  |
| `variant` | Yes      | string                                       | —                                                  |
| `value`   | Yes      | object                                       | The variant's JSON value.                          |
| `reason`  | Yes      | string                                       | disabled, rule_match or default; the set may grow. |

## FeatureFlagEvaluationList

No description.

| Property | Required | Type and constraints                                                        | Description |
| -------- | -------- | --------------------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`enum: ["list"]`)                                                   | —           |
| `data`   | Yes      | Array of [FeatureFlagEvaluation](/reference/schemas/#featureflagevaluation) | —           |

## FeatureFlagId

No description.

string (`pattern: "^flag_[0-9A-HJKMNP-TV-Z]{26}$"`)

## FeatureFlagList

No description.

| Property      | Required | Type and constraints                                    | Description |
| ------------- | -------- | ------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                               | —           |
| `data`        | Yes      | Array of [FeatureFlag](/reference/schemas/#featureflag) | —           |
| `has_more`    | Yes      | boolean                                                 | —           |
| `next_cursor` | Yes      | string or null                                          | —           |

## FeatureFlagRule

No description.

| Property     | Required | Type and constraints                                                      | Description |
| ------------ | -------- | ------------------------------------------------------------------------- | ----------- |
| `conditions` | Yes      | Array of [FeatureFlagCondition](/reference/schemas/#featureflagcondition) | —           |
| `serve`      | Yes      | [FeatureFlagServe](/reference/schemas/#featureflagserve)                  | —           |

## FeatureFlagServe

Exactly one of variant and rollout.

| Property    | Required | Type and constraints                                                | Description |
| ----------- | -------- | ------------------------------------------------------------------- | ----------- |
| `variant`   | No       | string                                                              | —           |
| `rollout`   | No       | Array of [FeatureFlagWeight](/reference/schemas/#featureflagweight) | —           |
| `bucket_by` | No       | string (`pattern: "^[A-Za-z0-9_.-]{1,64}$"`)                        | —           |

## FeatureFlagUpdate

No description.

| Property      | Required | Type and constraints                                                  | Description |
| ------------- | -------- | --------------------------------------------------------------------- | ----------- |
| `revision`    | Yes      | integer (`minimum: 1`)                                                | —           |
| `name`        | No       | string (`minLength: 1`; `maxLength: 200`)                             | —           |
| `description` | No       | string (`maxLength: 2000`)                                            | —           |
| `enabled`     | No       | boolean                                                               | —           |
| `variants`    | No       | Array of [FeatureFlagVariant](/reference/schemas/#featureflagvariant) | —           |
| `off_variant` | No       | string                                                                | —           |
| `rules`       | No       | Array of [FeatureFlagRule](/reference/schemas/#featureflagrule)       | —           |
| `fallthrough` | No       | [FeatureFlagServe](/reference/schemas/#featureflagserve)              | —           |

## FeatureFlagVariant

No description.

| Property | Required | Type and constraints                               | Description                   |
| -------- | -------- | -------------------------------------------------- | ----------------------------- |
| `key`    | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,127}$"`) | —                             |
| `value`  | Yes      | object                                             | Any JSON value (up to 4 KiB). |

## FeatureFlagWeight

No description.

| Property  | Required | Type and constraints                      | Description |
| --------- | -------- | ----------------------------------------- | ----------- |
| `variant` | Yes      | string                                    | —           |
| `weight`  | Yes      | integer (`minimum: 0`; `maximum: 100000`) | —           |

## ITEmailConfiguration

No description.

| Property        | Required | Type and constraints                                                     | Description |
| --------------- | -------- | ------------------------------------------------------------------------ | ----------- |
| `id`            | Yes      | string                                                                   | —           |
| `object`        | Yes      | string (`const: "it_email_configuration"`)                               | —           |
| `provider`      | Yes      | string (`enum: ["ses","postmark","resend","mailgun","sendgrid","smtp"]`) | —           |
| `from`          | Yes      | string                                                                   | —           |
| `sender_domain` | Yes      | [CustomDomainId](/reference/schemas/#customdomainid)                     | —           |
| `dns_verified`  | Yes      | boolean                                                                  | —           |
| `region`        | No       | string                                                                   | —           |
| `smtp_host`     | No       | string                                                                   | —           |
| `smtp_port`     | No       | integer                                                                  | —           |
| `templates`     | Yes      | Array of [ITEmailTemplate](/reference/schemas/#itemailtemplate)          | —           |
| `updated_at`    | Yes      | [Timestamp](/reference/schemas/#timestamp)                               | —           |

## ITEmailConfigurationPut

No description.

| Property            | Required | Type and constraints                                                     | Description |
| ------------------- | -------- | ------------------------------------------------------------------------ | ----------- |
| `provider`          | Yes      | string (`enum: ["ses","postmark","resend","mailgun","sendgrid","smtp"]`) | —           |
| `from`              | Yes      | string (`minLength: 1`; `maxLength: 320`)                                | —           |
| `sender_domain`     | Yes      | [CustomDomainId](/reference/schemas/#customdomainid)                     | —           |
| `region`            | No       | string (`maxLength: 64`)                                                 | —           |
| `smtp_host`         | No       | string (`maxLength: 253`)                                                | —           |
| `smtp_port`         | No       | integer (`enum: [465,587]`)                                              | —           |
| `token`             | No       | string (`minLength: 1`; `maxLength: 4096`)                               | —           |
| `access_key_id`     | No       | string (`minLength: 1`; `maxLength: 128`)                                | —           |
| `secret_access_key` | No       | string (`minLength: 1`; `maxLength: 4096`)                               | —           |
| `session_token`     | No       | string (`maxLength: 4096`)                                               | —           |
| `username`          | No       | string (`minLength: 1`; `maxLength: 320`)                                | —           |
| `password`          | No       | string (`minLength: 1`; `maxLength: 4096`)                               | —           |
| `templates`         | No       | Array of [ITEmailTemplate](/reference/schemas/#itemailtemplate)          | —           |

## ITEmailTemplate

Only literal organization_name, application_name, connection_name, action_url and expires_at placeholders are supported. No executable template expressions are accepted. The renderer appends immutable action and expiry blocks and requires truthful action and expiry values; otherwise platform defaults apply. Input limits count UTF-8 bytes as well as the schema character limits. Rendered text is limited to 32768 bytes and rendered HTML to 65536 bytes.

| Property   | Required | Type and constraints                                                                                                                            | Description                                                                      |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `category` | Yes      | string (`enum: ["setup_invitation","setup_reminder","certificate_warning","metadata_warning","idp_warning","rotation_notice","health_notice"]`) | —                                                                                |
| `subject`  | Yes      | string (`minLength: 1`; `maxLength: 200`)                                                                                                       | At most 200 UTF-8 bytes; action_url is forbidden in the subject.                 |
| `text`     | Yes      | string (`minLength: 1`; `maxLength: 16384`)                                                                                                     | At most 16384 UTF-8 bytes; plaintext is required.                                |
| `html`     | Yes      | string (`maxLength: 32768`)                                                                                                                     | At most 32768 UTF-8 bytes; only the supported sanitized text markup is accepted. |

## Import

No description.

| Property        | Required | Type and constraints                                                               | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------- | ----------- |
| `id`            | Yes      | [ImportId](/reference/schemas/#importid)                                           | —           |
| `object`        | Yes      | string (`const: "import"`)                                                         | —           |
| `source`        | Yes      | string (`enum: ["polis","workos","auth0","csv_saml","bundle"]`)                    | —           |
| `state`         | Yes      | string (`enum: ["planning","planned","running","completed","cancelled","failed"]`) | —           |
| `plan`          | No       | object                                                                             | —           |
| `bundle_source` | No       | string (`enum: ["polis","workos","auth0","csv_saml","generic"]`)                   | —           |
| `created_at`    | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |
| `updated_at`    | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |
| `completed_at`  | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |

## ImportBundle

The normalized migration format (version 1). It never carries secrets (OIDC client secrets, SCIM tokens, private keys). At most 16 MiB, 500 organizations and 100000 directory users.

| Property        | Required | Type and constraints                                                              | Description |
| --------------- | -------- | --------------------------------------------------------------------------------- | ----------- |
| `format`        | Yes      | string (`const: "ohauthcat.import_bundle"`)                                       | —           |
| `version`       | Yes      | integer (`const: 1`)                                                              | —           |
| `source`        | Yes      | string (`enum: ["polis","workos","auth0","csv_saml","generic"]`)                  | —           |
| `exported_at`   | No       | string                                                                            | —           |
| `organizations` | Yes      | Array of [ImportBundleOrganization](/reference/schemas/#importbundleorganization) | —           |

## ImportBundleConnection

No description.

| Property       | Required | Type and constraints                            | Description                                                                                                                                                                                                                                                                                     |
| -------------- | -------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy_id`    | Yes      | string (`minLength: 1`; `maxLength: 255`)       | —                                                                                                                                                                                                                                                                                               |
| `source_id`    | No       | string (`maxLength: 255`)                       | The object's ID in the system before the one that exported this bundle (an OhAuthCat export names the original ID of an imported object). Kept and exported again.                                                                                                                              |
| `type`         | Yes      | string (`enum: ["saml","oidc"]`)                | —                                                                                                                                                                                                                                                                                               |
| `name`         | No       | string (`maxLength: 200`)                       | —                                                                                                                                                                                                                                                                                               |
| `pending_oidc` | No       | boolean (`const: true`)                         | An OIDC connection whose discovery URL, client ID and client secret must be completed in the migration portal. Allowed only for type oidc, without saml or oidc configuration. The imported connection remains a draft until configured, tested and activated. False is rejected.               |
| `saml`         | No       | object (`additionalProperties: false`)          | —                                                                                                                                                                                                                                                                                               |
| `oidc`         | No       | object (`additionalProperties: false`)          | —                                                                                                                                                                                                                                                                                               |
| `profiles`     | No       | Array of object (`additionalProperties: false`) | The old vendor's profile IDs of this connection's users (at most 100000 per bundle). Each maps to the profile of `idp_subject` at the imported connection, so `POST /v1/sessions/migrate` resolves it before the user signs in here and the first sign-in's profile carries it in `legacy_ids`. |

## ImportBundleDirectory

No description.

| Property           | Required | Type and constraints                                                        | Description                                                                                                                                                                    |
| ------------------ | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `legacy_id`        | Yes      | string (`minLength: 1`; `maxLength: 255`)                                   | —                                                                                                                                                                              |
| `source_id`        | No       | string (`maxLength: 255`)                                                   | The object's ID in the system before the one that exported this bundle (an OhAuthCat export names the original ID of an imported object). Kept and exported again.             |
| `name`             | No       | string (`maxLength: 200`)                                                   | —                                                                                                                                                                              |
| `legacy_scim_urls` | No       | Array of string (`format: "uri"`)                                           | SCIM base URLs the IdP calls today on a customer-owned host (Lever A). Their paths are served as aliases of the directory; a request on one still needs the directory's token. |
| `provider`         | No       | string (`enum: ["okta","entra","google","onelogin","jumpcloud","generic"]`) | —                                                                                                                                                                              |
| `users`            | No       | Array of object (`additionalProperties: false`)                             | —                                                                                                                                                                              |
| `groups`           | No       | Array of object (`additionalProperties: false`)                             | —                                                                                                                                                                              |

## ImportBundleOrganization

No description.

| Property      | Required | Type and constraints                                                          | Description                                                                                                                                                        |
| ------------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `legacy_id`   | Yes      | string (`minLength: 1`; `maxLength: 255`)                                     | —                                                                                                                                                                  |
| `source_id`   | No       | string (`maxLength: 255`)                                                     | The object's ID in the system before the one that exported this bundle (an OhAuthCat export names the original ID of an imported object). Kept and exported again. |
| `name`        | Yes      | string (`minLength: 1`; `maxLength: 200`)                                     | —                                                                                                                                                                  |
| `external_id` | No       | string (`maxLength: 200`)                                                     | —                                                                                                                                                                  |
| `metadata`    | No       | object (`additionalProperties: {"type":"string","maxLength":500}`)            | —                                                                                                                                                                  |
| `domains`     | No       | Array of string                                                               | —                                                                                                                                                                  |
| `connections` | No       | Array of [ImportBundleConnection](/reference/schemas/#importbundleconnection) | —                                                                                                                                                                  |
| `directories` | No       | Array of [ImportBundleDirectory](/reference/schemas/#importbundledirectory)   | —                                                                                                                                                                  |

## ImportCreate

No description.

| Property            | Required | Type and constraints                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------- | -------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source`            | Yes      | string (`enum: ["polis","workos","auth0","csv_saml","bundle"]`) | The source to read. `auth0` and `csv_saml` are read only by their adapter (Auth0 `credentials`, or a `csv_saml` `bundle_upload_id`); an inline `bundle` with either source is refused with `parameter_invalid`. One environment has at most one planned or running `auth0` or `csv_saml` import; another answers `import_state_conflict` (409) until it completes, fails or is cancelled; `GET /v1/imports?state=planned` finds it, and a planned one is cancelled automatically after 24 hours. Creating `auth0` and `csv_saml` imports is also limited to 20 per hour per environment (`rate_limited`, 429, with `Retry-After`). A `csv_saml` archive names at most 100 distinct metadata URLs, each fetched once, and its whole read is bounded to 50 seconds. An `auth0` read, Management API retries included, is bounded to 50 seconds too.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `credentials`       | No       | object (`additionalProperties: {"type":"string"}`)              | Read the source's management API once, with these credentials, instead of sending a bundle. Polis/WorkOS authentication credentials and API keys are used only for this request, never stored. Auth0 uses tenant_domain, client_id and client_secret for a canonical Auth0 tenant host, with read:connections only; like Polis/WorkOS credentials they are used only for this request and never stored. Credentials are never logged or returned. Auth0 offset pagination refuses sources exceeding its documented 1000-connection capacity. Custom Auth0 tenant domains are currently refused. Nonsecret migration settings are copied into the normalized bundle and connection configuration and may appear in exports. `polis`: `base_url` (https), `api_key`, `product`, optional `sp_entity_id` (the deployment's SAML audience) and `external_url` (the deployment's `EXTERNAL_URL` when IdPs reach it on another origin than `base_url`; its shared ACS `&lt;external_url&gt;/api/oauth/saml` becomes `legacy_shared_acs_url`). `workos`: `api_key`, optional `base_url` (default `https://api.workos.com`); optional paired `custom_auth_domain` and `custom_auth_connections` configure custom-domain migration. The domain must be a canonical lowercase ASCII hostname, without a port or trailing dot. The connections value is a JSON array of objects with exactly `connection_id`, `acs_url` and `sp_entity_id`, copied from the actual WorkOS Service Provider Details; every imported active SAML connection needs one record and unknown, inactive, non-SAML or duplicate references are refused. Each ACS URL must use that exact domain. No vendor identifier or path is inferred. Each credential value is limited to 4096 bytes; larger setups can send a normalized bundle. WorkOS exports no IdP metadata, so its SAML connections import as drafts with `idp_metadata_required` until the IT admin supplies it through a `migration` portal link. Every request goes through the safe fetcher; a refused key or an unreachable or non-public source answers `import_source_unreachable`. |
| `bundle_upload_id`  | No       | [UploadId](/reference/schemas/#uploadid)                        | A valid, unexpired, unconsumed upload of this environment. csv_saml selects a closed ZIP containing connections.csv and flat named metadata XML files; other sources select import_bundle. The uploaded document must match its declared size and pass the same validation as an inline bundle. Consumption and creation of the planned import are atomic; workers use the frozen import bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `users_upload_id`   | No       | [UploadId](/reference/schemas/#uploadid)                        | Optional unconsumed auth0_users JSON lines export of this environment, at most 64 MiB. Allowed only with Auth0 credentials. The exporter must establish the unchanged upstream IdP subject; an unverified provider-specific identity is refused, and the original export is never returned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `mapping_upload_id` | No       | [UploadId](/reference/schemas/#uploadid)                        | Optional unconsumed auth0_mapping UTF-8 CSV with connection_id,organization_external_id,organization_name columns. Allowed only with Auth0 credentials, at most 5 MiB; explicit mapping takes precedence over source metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `bundle`            | No       | [ImportBundle](/reference/schemas/#importbundle)                | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## ImportId

No description.

string (`pattern: "^imp_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ImportList

No description.

| Property      | Required | Type and constraints                                        | Description |
| ------------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                    | —           |
| `data`        | Yes      | Array of [ImportSummary](/reference/schemas/#importsummary) | —           |
| `has_more`    | Yes      | boolean                                                     | —           |
| `next_cursor` | Yes      | string or null                                              | —           |

## ImportPlanItem

No description.

| Property    | Required | Type and constraints                                                | Description |
| ----------- | -------- | ------------------------------------------------------------------- | ----------- |
| `kind`      | Yes      | string (`enum: ["organization","domain","connection","directory"]`) | —           |
| `legacy_id` | No       | string                                                              | —           |
| `value`     | No       | string                                                              | —           |
| `action`    | Yes      | string (`enum: ["create","draft","skip"]`)                          | —           |
| `reason`    | No       | string                                                              | —           |
| `id`        | No       | string                                                              | —           |
| `blockers`  | No       | Array of string                                                     | —           |
| `users`     | No       | integer                                                             | —           |
| `groups`    | No       | integer                                                             | —           |

## ImportRollback

No description.

| Property  | Required | Type and constraints | Description                                                     |
| --------- | -------- | -------------------- | --------------------------------------------------------------- |
| `cleanup` | No       | boolean              | Also deactivate the organization's active imported connections. |

## ImportSummary

An import without its plan.

| Property        | Required | Type and constraints                                                               | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------- | ----------- |
| `id`            | Yes      | [ImportId](/reference/schemas/#importid)                                           | —           |
| `object`        | Yes      | string (`const: "import"`)                                                         | —           |
| `source`        | Yes      | string (`enum: ["polis","workos","auth0","csv_saml","bundle"]`)                    | —           |
| `state`         | Yes      | string (`enum: ["planning","planned","running","completed","cancelled","failed"]`) | —           |
| `bundle_source` | No       | string (`enum: ["polis","workos","auth0","csv_saml","generic"]`)                   | —           |
| `created_at`    | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |
| `updated_at`    | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |
| `completed_at`  | No       | [Timestamp](/reference/schemas/#timestamp)                                         | —           |

## Intent

`edit_connection` reopens one existing connection (the link's `connection`, required with it): its session may read, update, test and activate only that connection. `migration` lets the IT admin finish imported connections: supply the IdP metadata the old provider could not export (`POST /portal/migration/{conn}/metadata`), then test and activate them; it reaches only imported connections of the organization (and, with the link's `connection`, only that one). It also lists the organization's imported directories and rotates their SCIM token (`POST /portal/directories/{dir}/rotate_token`), which hands the token to the IT admin once. `log_streams` lets the IT admin add, list and delete log destinations for the organization's own sign-in records (`/portal/log_streams`); it needs a plan with log stream destinations. `encryption_keys` lets the IT admin register the organization's own AWS KMS key (`/portal/encryption_keys`); it needs an Enterprise plan. `audit_logs` lets the IT admin view and export the organization's Audit Logs product events (`/portal/audit_log_events`).

string (`enum: ["sso","dsync","domain_verification","edit_connection","migration","log_streams","encryption_keys","audit_logs"]`)

## ItContact

No description.

| Property     | Required | Type and constraints                           | Description |
| ------------ | -------- | ---------------------------------------------- | ----------- |
| `id`         | Yes      | [ItContactId](/reference/schemas/#itcontactid) | —           |
| `object`     | Yes      | string (`const: "it_contact"`)                 | —           |
| `email`      | Yes      | string (`format: "email"`)                     | —           |
| `role`       | Yes      | string (`enum: ["owner","viewer"]`)            | —           |
| `notify`     | No       | Array of string                                | —           |
| `created_at` | No       | [Timestamp](/reference/schemas/#timestamp)     | —           |

## ItContactCreate

No description.

| Property | Required | Type and constraints                | Description |
| -------- | -------- | ----------------------------------- | ----------- |
| `email`  | Yes      | string (`format: "email"`)          | —           |
| `role`   | Yes      | string (`enum: ["owner","viewer"]`) | —           |
| `notify` | No       | Array of string                     | —           |

## ItContactId

No description.

string (`pattern: "^itc_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ItContactList

No description.

| Property      | Required | Type and constraints                                | Description |
| ------------- | -------- | --------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                            | —           |
| `data`        | Yes      | Array of [ItContact](/reference/schemas/#itcontact) | —           |
| `has_more`    | Yes      | boolean                                             | —           |
| `next_cursor` | Yes      | string or null                                      | —           |

## ItContactUpdate

No description.

| Property | Required | Type and constraints                | Description |
| -------- | -------- | ----------------------------------- | ----------- |
| `role`   | No       | string (`enum: ["owner","viewer"]`) | —           |
| `notify` | No       | Array of string                     | —           |

## LegacyIds

No description.

object (`additionalProperties: {"type":"string"}`)

## LogStream

No description.

| Property          | Required | Type and constraints                                  | Description                                                                                                                                    |
| ----------------- | -------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Yes      | [LogStreamId](/reference/schemas/#logstreamid)        | —                                                                                                                                              |
| `object`          | Yes      | string (`enum: ["log_stream"]`)                       | —                                                                                                                                              |
| `type`            | Yes      | string (`enum: ["datadog","splunk_hec","http","s3"]`) | —                                                                                                                                              |
| `created_at`      | Yes      | string (`format: "date-time"`)                        | —                                                                                                                                              |
| `endpoint`        | No       | string                                                | —                                                                                                                                              |
| `region`          | No       | string                                                | —                                                                                                                                              |
| `bucket`          | No       | string                                                | —                                                                                                                                              |
| `prefix`          | No       | string                                                | —                                                                                                                                              |
| `organization`    | No       | [OrganizationId](/reference/schemas/#organizationid)  | Set on a destination added in the setup portal; it receives only this organization's sign-in records. Absent on environment-wide destinations. |
| `usage_month`     | Yes      | string (`pattern: "^[0-9]{4}-(0[1-9]&#124;1[0-2])$"`) | UTC month containing the acknowledged delivery result.                                                                                         |
| `delivered_bytes` | Yes      | string (`pattern: "^(0&#124;[1-9][0-9]{0,18})$"`)     | Uncompressed accepted transport bytes, counted once per immutable delivery. No charging is performed.                                          |

## LogStreamCreate

No description.

| Property            | Required | Type and constraints                                  | Description                                                                   |
| ------------------- | -------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
| `type`              | Yes      | string (`enum: ["datadog","splunk_hec","http","s3"]`) | —                                                                             |
| `endpoint`          | No       | string (`maxLength: 2048`)                            | HTTPS URL without user information, query or fragment. Redirects are refused. |
| `token`             | No       | string (`minLength: 1`; `maxLength: 4096`)            | —                                                                             |
| `region`            | No       | string (`maxLength: 64`)                              | —                                                                             |
| `bucket`            | No       | string (`maxLength: 63`)                              | —                                                                             |
| `prefix`            | No       | string (`maxLength: 256`)                             | —                                                                             |
| `access_key_id`     | No       | string (`maxLength: 128`)                             | —                                                                             |
| `secret_access_key` | No       | string (`maxLength: 4096`)                            | —                                                                             |
| `session_token`     | No       | string (`maxLength: 4096`)                            | —                                                                             |

## LogStreamId

No description.

string (`pattern: "^lst_[0-9A-HJKMNP-TV-Z]{26}$"`)

## LogStreamList

No description.

| Property | Required | Type and constraints                                | Description |
| -------- | -------- | --------------------------------------------------- | ----------- |
| `object` | Yes      | string (`enum: ["list"]`)                           | —           |
| `data`   | Yes      | Array of [LogStream](/reference/schemas/#logstream) | —           |

## M2MAudience

A resource indicator (RFC 8707), an https URI or a URN. Tokens are issued for exactly one registered audience.

string (`maxLength: 512`)

## M2MAuthMethod

No description.

string (`enum: ["client_secret","private_key_jwt"]`)

## M2MClient

No description.

| Property                     | Required | Type and constraints                                    | Description                                     |
| ---------------------------- | -------- | ------------------------------------------------------- | ----------------------------------------------- |
| `id`                         | Yes      | [M2MClientId](/reference/schemas/#m2mclientid)          | —                                               |
| `object`                     | Yes      | string (`const: "m2m_client"`)                          | —                                               |
| `organization`               | No       | [OrganizationId](/reference/schemas/#organizationid)    | —                                               |
| `name`                       | Yes      | string (`maxLength: 200`)                               | —                                               |
| `auth_method`                | Yes      | [M2MAuthMethod](/reference/schemas/#m2mauthmethod)      | —                                               |
| `secret_hint`                | No       | string                                                  | The last four characters of the current secret. |
| `previous_secret_expires_at` | No       | string (`format: "date-time"`)                          | —                                               |
| `jwks`                       | No       | object (`additionalProperties: true`)                   | The registered public keys (private_key_jwt).   |
| `scopes`                     | Yes      | Array of [M2MScope](/reference/schemas/#m2mscope)       | —                                               |
| `audiences`                  | Yes      | Array of [M2MAudience](/reference/schemas/#m2maudience) | —                                               |
| `access_token_seconds`       | Yes      | integer (`minimum: 60`; `maximum: 3600`)                | —                                               |
| `revoked_at`                 | No       | string (`format: "date-time"`)                          | —                                               |
| `last_used_at`               | No       | string (`format: "date-time"`)                          | —                                               |
| `created_at`                 | Yes      | string (`format: "date-time"`)                          | —                                               |
| `updated_at`                 | Yes      | string (`format: "date-time"`)                          | —                                               |

## M2MClientCreate

No description.

| Property               | Required | Type and constraints                                    | Description |
| ---------------------- | -------- | ------------------------------------------------------- | ----------- |
| `name`                 | Yes      | string (`minLength: 1`; `maxLength: 200`)               | —           |
| `organization`         | No       | [OrganizationId](/reference/schemas/#organizationid)    | —           |
| `auth_method`          | No       | [M2MAuthMethod](/reference/schemas/#m2mauthmethod)      | —           |
| `jwks`                 | No       | object (`additionalProperties: true`)                   | —           |
| `scopes`               | No       | Array of [M2MScope](/reference/schemas/#m2mscope)       | —           |
| `audiences`            | Yes      | Array of [M2MAudience](/reference/schemas/#m2maudience) | —           |
| `access_token_seconds` | No       | integer (`minimum: 60`; `maximum: 3600`)                | —           |

## M2MClientId

No description.

string (`pattern: "^mcli_[0-9A-HJKMNP-TV-Z]{26}$"`)

## M2MClientList

No description.

| Property      | Required | Type and constraints                                | Description |
| ------------- | -------- | --------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                            | —           |
| `data`        | Yes      | Array of [M2MClient](/reference/schemas/#m2mclient) | —           |
| `has_more`    | Yes      | boolean                                             | —           |
| `next_cursor` | Yes      | string or null                                      | —           |

## M2MClientUpdate

No description.

| Property               | Required | Type and constraints                                    | Description |
| ---------------------- | -------- | ------------------------------------------------------- | ----------- |
| `name`                 | No       | string (`minLength: 1`; `maxLength: 200`)               | —           |
| `jwks`                 | No       | object (`additionalProperties: true`)                   | —           |
| `scopes`               | No       | Array of [M2MScope](/reference/schemas/#m2mscope)       | —           |
| `audiences`            | No       | Array of [M2MAudience](/reference/schemas/#m2maudience) | —           |
| `access_token_seconds` | No       | integer (`minimum: 60`; `maximum: 3600`)                | —           |

## M2MClientWithSecret

No description.

| Property        | Required | Type and constraints                       | Description                                  |
| --------------- | -------- | ------------------------------------------ | -------------------------------------------- |
| `client`        | Yes      | [M2MClient](/reference/schemas/#m2mclient) | —                                            |
| `client_secret` | No       | string                                     | Shown once. Store it in your secret manager. |

## M2MScope

No description.

string (`pattern: "^[\\x21\\x23-\\x5B\\x5D-\\x7E]{1,128}$"`)

## M2MSecretRotate

No description.

| Property        | Required | Type and constraints | Description                               |
| --------------- | -------- | -------------------- | ----------------------------------------- |
| `keep_previous` | No       | boolean              | Keep the old secret working for 24 hours. |

## MCPResponse

Bounded JSON-RPC response decoded by the dedicated MCP transport.

object (`additionalProperties: true`)

## Membership

No description.

| Property       | Required | Type and constraints                                   | Description |
| -------------- | -------- | ------------------------------------------------------ | ----------- |
| `id`           | Yes      | [MembershipId](/reference/schemas/#membershipid)       | —           |
| `object`       | Yes      | string (`const: "organization_membership"`)            | —           |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid)   | —           |
| `user`         | Yes      | [EndUserId](/reference/schemas/#enduserid)             | —           |
| `role`         | Yes      | [MembershipRole](/reference/schemas/#membershiprole)   | —           |
| `state`        | Yes      | [MembershipState](/reference/schemas/#membershipstate) | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                         | —           |
| `updated_at`   | Yes      | string (`format: "date-time"`)                         | —           |

## MembershipCreate

No description.

| Property | Required | Type and constraints                                 | Description |
| -------- | -------- | ---------------------------------------------------- | ----------- |
| `user`   | Yes      | [EndUserId](/reference/schemas/#enduserid)           | —           |
| `role`   | No       | [MembershipRole](/reference/schemas/#membershiprole) | —           |

## MembershipId

No description.

string (`pattern: "^om_[0-9A-HJKMNP-TV-Z]{26}$"`)

## MembershipList

No description.

| Property      | Required | Type and constraints                                  | Description |
| ------------- | -------- | ----------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                              | —           |
| `data`        | Yes      | Array of [Membership](/reference/schemas/#membership) | —           |
| `has_more`    | Yes      | boolean                                               | —           |
| `next_cursor` | Yes      | string or null                                        | —           |

## MembershipPermissions

No description.

| Property               | Required | Type and constraints                                          | Description                                  |
| ---------------------- | -------- | ------------------------------------------------------------- | -------------------------------------------- |
| `object`               | Yes      | string (`const: "membership_permissions"`)                    | —                                            |
| `membership`           | Yes      | [MembershipId](/reference/schemas/#membershipid)              | —                                            |
| `roles`                | Yes      | Array of [MembershipRole](/reference/schemas/#membershiprole) | Highest priority first.                      |
| `permissions`          | Yes      | Array of [PermissionSlug](/reference/schemas/#permissionslug) | —                                            |
| `resource_permissions` | No       | Array of [PermissionSlug](/reference/schemas/#permissionslug) | Extra permissions on the requested resource. |

## MembershipRole

The role's slug in the developer's app.

string (`pattern: "^[a-z0-9][a-z0-9_-]{0,63}$"`)

## MembershipState

No description.

string (`enum: ["active","inactive"]`)

## MembershipUpdate

No description.

| Property | Required | Type and constraints                                   | Description |
| -------- | -------- | ------------------------------------------------------ | ----------- |
| `role`   | No       | [MembershipRole](/reference/schemas/#membershiprole)   | —           |
| `state`  | No       | [MembershipState](/reference/schemas/#membershipstate) | —           |

## Metadata

No description.

object (`additionalProperties: {"type":"string","maxLength":500}`)

## OAuthClient

No description.

| Property                    | Required | Type and constraints                                                                                                                 | Description                                                                                                                                              |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                        | Yes      | [OAuthClientId](/reference/schemas/#oauthclientid)                                                                                   | —                                                                                                                                                        |
| `object`                    | Yes      | string (`const: "oauth_client"`)                                                                                                     | —                                                                                                                                                        |
| `name`                      | Yes      | string                                                                                                                               | —                                                                                                                                                        |
| `type`                      | Yes      | string (`enum: ["confidential","public"]`)                                                                                           | —                                                                                                                                                        |
| `redirect_uris`             | Yes      | Array of string                                                                                                                      | —                                                                                                                                                        |
| `post_logout_redirect_uris` | No       | Array of string                                                                                                                      | Where RP-initiated logout (/oauth/{env}/logout) may send the browser afterwards, exact match. Absent on clients created before it existed reads as none. |
| `grant_types`               | Yes      | Array of string (`enum: ["authorization_code","refresh_token","client_credentials","urn:ietf:params:oauth:grant-type:device_code"]`) | —                                                                                                                                                        |
| `scopes`                    | Yes      | Array of string                                                                                                                      | —                                                                                                                                                        |
| `consent_text`              | Yes      | string or null                                                                                                                       | —                                                                                                                                                        |
| `logo_uri`                  | Yes      | string or null                                                                                                                       | —                                                                                                                                                        |
| `third_party`               | Yes      | boolean                                                                                                                              | —                                                                                                                                                        |
| `registration`              | Yes      | string (`enum: ["managed","dynamic"]`)                                                                                               | —                                                                                                                                                        |
| `secret_set_at`             | Yes      | string or null (`format: "date-time"`)                                                                                               | —                                                                                                                                                        |
| `created_at`                | Yes      | string (`format: "date-time"`)                                                                                                       | —                                                                                                                                                        |
| `updated_at`                | Yes      | string (`format: "date-time"`)                                                                                                       | —                                                                                                                                                        |

## OAuthClientCreated

No description.

| Property        | Required | Type and constraints                           | Description                           |
| --------------- | -------- | ---------------------------------------------- | ------------------------------------- |
| `client`        | Yes      | [OAuthClient](/reference/schemas/#oauthclient) | —                                     |
| `client_secret` | Yes      | string or null                                 | Shown once, for confidential clients. |

## OAuthClientId

No description.

string (`pattern: "^ocl_[0-9A-HJKMNP-TV-Z]{26}$"`)

## OAuthClientInput

No description.

| Property                    | Required | Type and constraints                                                                                                                 | Description                                                                                                                                                                    |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                      | Yes      | string (`minLength: 1`; `maxLength: 100`)                                                                                            | —                                                                                                                                                                              |
| `type`                      | Yes      | string (`enum: ["confidential","public"]`)                                                                                           | Ignored on update: a client never changes type.                                                                                                                                |
| `redirect_uris`             | No       | Array of string (`maxLength: 2048`)                                                                                                  | —                                                                                                                                                                              |
| `post_logout_redirect_uris` | No       | Array of string (`maxLength: 2048`)                                                                                                  | Where RP-initiated logout may send the browser afterwards; the redirect URI rules apply (https, or loopback and private-use schemes for public clients). Absent reads as none. |
| `grant_types`               | Yes      | Array of string (`enum: ["authorization_code","refresh_token","client_credentials","urn:ietf:params:oauth:grant-type:device_code"]`) | —                                                                                                                                                                              |
| `scopes`                    | No       | Array of string                                                                                                                      | —                                                                                                                                                                              |
| `consent_text`              | No       | string or null (`maxLength: 500`)                                                                                                    | —                                                                                                                                                                              |
| `logo_uri`                  | No       | string or null (`maxLength: 2048`)                                                                                                   | —                                                                                                                                                                              |
| `third_party`               | No       | boolean                                                                                                                              | —                                                                                                                                                                              |

## OAuthClientList

No description.

| Property   | Required | Type and constraints                                    | Description |
| ---------- | -------- | ------------------------------------------------------- | ----------- |
| `object`   | Yes      | string (`const: "list"`)                                | —           |
| `data`     | Yes      | Array of [OAuthClient](/reference/schemas/#oauthclient) | —           |
| `has_more` | Yes      | boolean                                                 | —           |

## OAuthClientSecret

No description.

| Property                     | Required | Type and constraints                    | Description |
| ---------------------------- | -------- | --------------------------------------- | ----------- |
| `object`                     | Yes      | string (`const: "oauth_client_secret"`) | —           |
| `client_secret`              | Yes      | string                                  | Shown once. |
| `previous_secret_expires_at` | Yes      | string (`format: "date-time"`)          | —           |

## OAuthGrant

No description.

| Property       | Required | Type and constraints                               | Description                                                       |
| -------------- | -------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| `id`           | Yes      | [OAuthGrantId](/reference/schemas/#oauthgrantid)   | —                                                                 |
| `object`       | Yes      | string (`const: "oauth_grant"`)                    | —                                                                 |
| `client`       | Yes      | [OAuthClientId](/reference/schemas/#oauthclientid) | —                                                                 |
| `client_name`  | Yes      | string                                             | —                                                                 |
| `user`         | Yes      | [EndUserId](/reference/schemas/#enduserid)         | —                                                                 |
| `organization` | Yes      | string or null                                     | —                                                                 |
| `scopes`       | Yes      | Array of string                                    | —                                                                 |
| `resources`    | Yes      | Array of string                                    | —                                                                 |
| `agent`        | Yes      | boolean                                            | True for dynamically registered clients (agents and MCP clients). |
| `created_at`   | Yes      | string (`format: "date-time"`)                     | —                                                                 |
| `updated_at`   | Yes      | string (`format: "date-time"`)                     | —                                                                 |

## OAuthGrantId

No description.

string (`pattern: "^ogr_[0-9A-HJKMNP-TV-Z]{26}$"`)

## OAuthGrantList

No description.

| Property   | Required | Type and constraints                                  | Description |
| ---------- | -------- | ----------------------------------------------------- | ----------- |
| `object`   | Yes      | string (`const: "list"`)                              | —           |
| `data`     | Yes      | Array of [OAuthGrant](/reference/schemas/#oauthgrant) | —           |
| `has_more` | Yes      | boolean                                               | —           |

## OAuthOrganizationRevoke

No description.

| Property           | Required | Type and constraints       | Description |
| ------------------ | -------- | -------------------------- | ----------- |
| `third_party_only` | No       | boolean (`default: false`) | —           |

## OAuthOrganizationRevokeResult

No description.

| Property  | Required | Type and constraints                       | Description |
| --------- | -------- | ------------------------------------------ | ----------- |
| `object`  | Yes      | string (`const: "oauth_grant_revocation"`) | —           |
| `revoked` | Yes      | integer                                    | —           |

## OAuthProtectedResourceMetadata

No description.

| Property                   | Required | Type and constraints | Description |
| -------------------------- | -------- | -------------------- | ----------- |
| `resource`                 | Yes      | string               | —           |
| `authorization_servers`    | Yes      | Array of string      | —           |
| `scopes_supported`         | Yes      | Array of string      | —           |
| `bearer_methods_supported` | Yes      | Array of string      | —           |
| `resource_name`            | No       | string               | —           |

## OAuthResource

No description.

| Property                   | Required | Type and constraints                                   | Description                                                                                               |
| -------------------------- | -------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `id`                       | Yes      | [OAuthResourceId](/reference/schemas/#oauthresourceid) | —                                                                                                         |
| `object`                   | Yes      | string (`const: "oauth_resource"`)                     | —                                                                                                         |
| `identifier`               | Yes      | string                                                 | The absolute URI tokens for this resource carry as aud (RFC 8707).                                        |
| `name`                     | Yes      | string                                                 | —                                                                                                         |
| `kind`                     | Yes      | string (`enum: ["api","mcp"]`)                         | —                                                                                                         |
| `scopes`                   | Yes      | Array of string                                        | —                                                                                                         |
| `dynamic_registration`     | Yes      | boolean                                                | Whether clients may register themselves (RFC 7591) to reach this resource; on by default for MCP servers. |
| `access_token_ttl_seconds` | Yes      | integer                                                | —                                                                                                         |
| `issuer`                   | Yes      | string                                                 | The environment's authorization server issuer.                                                            |
| `created_at`               | Yes      | string (`format: "date-time"`)                         | —                                                                                                         |
| `updated_at`               | Yes      | string (`format: "date-time"`)                         | —                                                                                                         |

## OAuthResourceCreate

No description.

| Property                   | Required | Type and constraints                       | Description |
| -------------------------- | -------- | ------------------------------------------ | ----------- |
| `identifier`               | Yes      | string (`minLength: 1`; `maxLength: 2048`) | —           |
| `name`                     | Yes      | string (`minLength: 1`; `maxLength: 100`)  | —           |
| `kind`                     | Yes      | string (`enum: ["api","mcp"]`)             | —           |
| `scopes`                   | No       | Array of string                            | —           |
| `dynamic_registration`     | No       | boolean                                    | —           |
| `access_token_ttl_seconds` | No       | integer (`minimum: 60`; `maximum: 3600`)   | —           |

## OAuthResourceId

No description.

string (`pattern: "^ores_[0-9A-HJKMNP-TV-Z]{26}$"`)

## OAuthResourceList

No description.

| Property | Required | Type and constraints                                        | Description |
| -------- | -------- | ----------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                    | —           |
| `data`   | Yes      | Array of [OAuthResource](/reference/schemas/#oauthresource) | —           |

## OAuthResourceUpdate

No description.

| Property                   | Required | Type and constraints                      | Description |
| -------------------------- | -------- | ----------------------------------------- | ----------- |
| `name`                     | Yes      | string (`minLength: 1`; `maxLength: 100`) | —           |
| `scopes`                   | No       | Array of string                           | —           |
| `dynamic_registration`     | No       | boolean                                   | —           |
| `access_token_ttl_seconds` | No       | integer (`minimum: 60`; `maximum: 3600`)  | —           |

## OAuthScope

No description.

| Property      | Required | Type and constraints            | Description |
| ------------- | -------- | ------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "oauth_scope"`) | —           |
| `name`        | Yes      | string                          | —           |
| `description` | Yes      | string                          | —           |
| `created_at`  | Yes      | string (`format: "date-time"`)  | —           |

## OAuthScopeInput

No description.

| Property      | Required | Type and constraints                      | Description |
| ------------- | -------- | ----------------------------------------- | ----------- |
| `description` | Yes      | string (`minLength: 1`; `maxLength: 300`) | —           |

## OAuthScopeList

No description.

| Property | Required | Type and constraints                                  | Description |
| -------- | -------- | ----------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                              | —           |
| `data`   | Yes      | Array of [OAuthScope](/reference/schemas/#oauthscope) | —           |

## Organization

No description.

| Property          | Required | Type and constraints                                 | Description                                                                                                                    |
| ----------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                                                                                              |
| `object`          | Yes      | string (`const: "organization"`)                     | —                                                                                                                              |
| `legacy_ids`      | No       | [LegacyIds](/reference/schemas/#legacyids)           | IDs of this object in the system it was imported from, by source (e.g. `{"workos":"org_…"}`); absent when it was not imported. |
| `name`            | Yes      | string                                               | —                                                                                                                              |
| `external_id`     | No       | string or null                                       | —                                                                                                                              |
| `status`          | Yes      | string (`enum: ["active","inactive"]`)               | —                                                                                                                              |
| `allowed_intents` | No       | Array of [Intent](/reference/schemas/#intent)        | —                                                                                                                              |
| `consent_screen`  | No       | string (`enum: ["environment_default","on","off"]`)  | —                                                                                                                              |
| `metadata`        | No       | [Metadata](/reference/schemas/#metadata)             | —                                                                                                                              |
| `created_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —                                                                                                                              |
| `updated_at`      | No       | [Timestamp](/reference/schemas/#timestamp)           | —                                                                                                                              |

## OrganizationAllowedIntents

No description.

| Property          | Required | Type and constraints                                 | Description |
| ----------------- | -------- | ---------------------------------------------------- | ----------- |
| `object`          | Yes      | string (`const: "organization_allowed_intents"`)     | —           |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `allowed_intents` | Yes      | Array of [Intent](/reference/schemas/#intent)        | —           |

## OrganizationAllowedIntentsUpdate

No description.

| Property          | Required | Type and constraints                          | Description |
| ----------------- | -------- | --------------------------------------------- | ----------- |
| `allowed_intents` | Yes      | Array of [Intent](/reference/schemas/#intent) | —           |

## OrganizationApiKeyCreate

No description.

| Property        | Required | Type and constraints                       | Description                                                     |
| --------------- | -------- | ------------------------------------------ | --------------------------------------------------------------- |
| `name`          | Yes      | string (`minLength: 1`; `maxLength: 200`)  | —                                                               |
| `scopes`        | Yes      | Array of string                            | —                                                               |
| `ip_allow_list` | No       | Array of string                            | CIDR blocks the key may be used from (Business plan and above). |
| `expires_at`    | No       | [Timestamp](/reference/schemas/#timestamp) | —                                                               |

## OrganizationCreate

No description.

| Property          | Required | Type and constraints                                | Description                                                                                                                                       |
| ----------------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | Yes      | string (`minLength: 1`; `maxLength: 200`)           | —                                                                                                                                                 |
| `external_id`     | No       | string (`minLength: 1`; `maxLength: 200`)           | —                                                                                                                                                 |
| `domains`         | No       | Array of string                                     | —                                                                                                                                                 |
| `allowed_intents` | No       | Array of [Intent](/reference/schemas/#intent)       | —                                                                                                                                                 |
| `consent_screen`  | No       | string (`enum: ["environment_default","on","off"]`) | Whether this organization's users see the consent screen; `environment_default` (the default) follows the environment's `consent_screen_default`. |
| `metadata`        | No       | [Metadata](/reference/schemas/#metadata)            | —                                                                                                                                                 |

## OrganizationExport

No description.

| Property     | Required | Type and constraints                                             | Description |
| ------------ | -------- | ---------------------------------------------------------------- | ----------- |
| `id`         | Yes      | [OrganizationExportId](/reference/schemas/#organizationexportid) | —           |
| `object`     | Yes      | string (`const: "organization_export"`)                          | —           |
| `state`      | Yes      | string (`enum: ["pending","ready","failed"]`)                    | —           |
| `row_count`  | No       | integer                                                          | —           |
| `url`        | No       | string or null (`format: "uri"`)                                 | —           |
| `expires_at` | No       | string or null (`format: "date-time"`)                           | —           |

## OrganizationExportCreate

No description.

| Property   | Required | Type and constraints                                               | Description                                                    |
| ---------- | -------- | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| `metadata` | No       | object (`additionalProperties: {"type":"string","maxLength":500}`) | Exact metadata filter, like `metadata[key]=value` on the list. |

## OrganizationExportId

No description.

string (`pattern: "^oexp_[0-9A-HJKMNP-TV-Z]{26}$"`)

## OrganizationId

No description.

string (`pattern: "^org_[0-9A-HJKMNP-TV-Z]{26}$"`)

## OrganizationList

No description.

| Property      | Required | Type and constraints                                      | Description |
| ------------- | -------- | --------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                  | —           |
| `data`        | Yes      | Array of [Organization](/reference/schemas/#organization) | —           |
| `has_more`    | Yes      | boolean                                                   | —           |
| `next_cursor` | Yes      | string or null                                            | —           |

## OrganizationOAuthSettings

No description.

| Property           | Required | Type and constraints                                 | Description |
| ------------------ | -------- | ---------------------------------------------------- | ----------- |
| `object`           | Yes      | string (`const: "organization_oauth_settings"`)      | —           |
| `organization`     | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `third_party_apps` | Yes      | string (`enum: ["allow","deny"]`)                    | —           |

## OrganizationOAuthSettingsInput

No description.

| Property           | Required | Type and constraints              | Description |
| ------------------ | -------- | --------------------------------- | ----------- |
| `third_party_apps` | Yes      | string (`enum: ["allow","deny"]`) | —           |

## OrganizationProfile

No description.

| Property             | Required | Type and constraints                                 | Description                                                                 |
| -------------------- | -------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
| `object`             | Yes      | string (`const: "organization_profile"`)             | —                                                                           |
| `organization_id`    | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                                           |
| `slug`               | No       | string                                               | —                                                                           |
| `logo_url`           | No       | string                                               | —                                                                           |
| `primary_color`      | No       | string                                               | Branding override (#rrggbb); absent falls back to the environment branding. |
| `effective_logo_url` | No       | string                                               | logo_url, or the environment branding logo when unset.                      |

## OrganizationProfileUpdate

No description.

| Property        | Required | Type and constraints | Description |
| --------------- | -------- | -------------------- | ----------- |
| `slug`          | No       | string or null       | —           |
| `logo_url`      | No       | string or null       | —           |
| `primary_color` | No       | string or null       | —           |

## OrganizationSetupStatus

No description.

| Property          | Required | Type and constraints                                 | Description |
| ----------------- | -------- | ---------------------------------------------------- | ----------- |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `intents`         | Yes      | Array of object                                      | —           |

## OrganizationUpdate

No description.

| Property          | Required | Type and constraints                                | Description |
| ----------------- | -------- | --------------------------------------------------- | ----------- |
| `name`            | No       | string (`minLength: 1`; `maxLength: 200`)           | —           |
| `external_id`     | No       | string or null                                      | —           |
| `allowed_intents` | No       | Array of [Intent](/reference/schemas/#intent)       | —           |
| `consent_screen`  | No       | string (`enum: ["environment_default","on","off"]`) | —           |
| `metadata`        | No       | [Metadata](/reference/schemas/#metadata)            | —           |

## OrganizationUserManagementSettings

No description.

| Property       | Required | Type and constraints | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mfa_required` | Yes      | boolean              | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `methods`      | No       | array or null        | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `sso_required` | No       | boolean              | End users whose email is on one of the organization's verified domains must sign in with SSO. The hosted login routes them to the organization's SSO when it can (an active, tested connection and a flow started by an app) and otherwise refuses with `end_user_sso_required`; password, magic-code, passkey and social first factors (hosted and headless) are refused with `end_user_sso_required` for them. Domains without the policy answer exactly as before, so the identify step reveals nothing about a domain that does not route to SSO. Default false; omitted on update keeps false. |

## PassportGrants

No description.

| Property       | Required | Type and constraints | Description |
| -------------- | -------- | -------------------- | ----------- |
| `domain_proof` | Yes      | boolean              | —           |
| `guidance`     | Yes      | boolean              | —           |
| `read`         | Yes      | boolean              | —           |

## PassportLink

A Passport linked to one of your organizations, as the vendor sees it.

| Property          | Required | Type and constraints                                 | Description            |
| ----------------- | -------- | ---------------------------------------------------- | ---------------------- |
| `object`          | Yes      | string (`enum: ["passport_link"]`)                   | —                      |
| `id`              | Yes      | string                                               | The link ID (`pptl_`). |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                      |
| `status`          | Yes      | string (`enum: ["linked","unlinked"]`)               | —                      |
| `linked_at`       | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —                      |
| `unlinked_at`     | Yes      | string or null (`format: "date-time"`)               | —                      |
| `grants`          | Yes      | [PassportGrants](/reference/schemas/#passportgrants) | —                      |

## PassportLinkList

No description.

| Property      | Required | Type and constraints                                      | Description |
| ------------- | -------- | --------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                 | —           |
| `data`        | Yes      | Array of [PassportLink](/reference/schemas/#passportlink) | —           |
| `has_more`    | Yes      | boolean                                                   | —           |
| `next_cursor` | Yes      | string or null                                            | —           |

## Permission

No description.

| Property      | Required | Type and constraints                                 | Description |
| ------------- | -------- | ---------------------------------------------------- | ----------- |
| `id`          | Yes      | [PermissionId](/reference/schemas/#permissionid)     | —           |
| `object`      | Yes      | string (`const: "permission"`)                       | —           |
| `slug`        | Yes      | [PermissionSlug](/reference/schemas/#permissionslug) | —           |
| `name`        | No       | string (`maxLength: 200`)                            | —           |
| `description` | No       | string (`maxLength: 1000`)                           | —           |
| `created_at`  | Yes      | string (`format: "date-time"`)                       | —           |
| `updated_at`  | Yes      | string (`format: "date-time"`)                       | —           |

## PermissionCreate

No description.

| Property      | Required | Type and constraints                                 | Description |
| ------------- | -------- | ---------------------------------------------------- | ----------- |
| `slug`        | Yes      | [PermissionSlug](/reference/schemas/#permissionslug) | —           |
| `name`        | No       | string (`maxLength: 200`)                            | —           |
| `description` | No       | string (`maxLength: 1000`)                           | —           |

## PermissionId

No description.

string (`pattern: "^perm_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PermissionList

No description.

| Property      | Required | Type and constraints                                  | Description |
| ------------- | -------- | ----------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                              | —           |
| `data`        | Yes      | Array of [Permission](/reference/schemas/#permission) | —           |
| `has_more`    | Yes      | boolean                                               | —           |
| `next_cursor` | Yes      | string or null                                        | —           |

## PermissionSlug

A permission the developer's app checks, such as `reports:read`.

string (`pattern: "^[a-z0-9][a-z0-9_.:-]{0,127}$"`)

## PermissionUpdate

No description.

| Property      | Required | Type and constraints               | Description |
| ------------- | -------- | ---------------------------------- | ----------- |
| `name`        | No       | string or null (`maxLength: 200`)  | —           |
| `description` | No       | string or null (`maxLength: 1000`) | —           |

## PipeAccessToken

No description.

| Property       | Required | Type and constraints                       | Description |
| -------------- | -------- | ------------------------------------------ | ----------- |
| `object`       | Yes      | string (`enum: ["pipe_access_token"]`)     | —           |
| `access_token` | Yes      | string                                     | —           |
| `token_type`   | No       | string                                     | —           |
| `expires_at`   | No       | [Timestamp](/reference/schemas/#timestamp) | —           |
| `scopes`       | Yes      | Array of string                            | —           |

## PipeConnectSession

No description.

| Property      | Required | Type and constraints                                 | Description |
| ------------- | -------- | ---------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["pipe_connect_session"]`)            | —           |
| `connection`  | Yes      | [PipeConnection](/reference/schemas/#pipeconnection) | —           |
| `connect_url` | Yes      | string (`format: "uri"`)                             | —           |
| `expires_at`  | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —           |

## PipeConnection

No description.

| Property          | Required | Type and constraints                                            | Description                                                                                              |
| ----------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `object`          | Yes      | string (`enum: ["pipe_connection"]`)                            | —                                                                                                        |
| `id`              | Yes      | [PipeConnectionId](/reference/schemas/#pipeconnectionid)        | —                                                                                                        |
| `provider`        | Yes      | string                                                          | —                                                                                                        |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid)            | —                                                                                                        |
| `user_id`         | Yes      | string                                                          | —                                                                                                        |
| `state`           | Yes      | string (`enum: ["pending","connected","error","disconnected"]`) | —                                                                                                        |
| `scopes`          | Yes      | Array of string                                                 | —                                                                                                        |
| `last_error`      | No       | string                                                          | Why the connection is in error (access_denied, token_exchange_failed, refresh_failed, provider_missing). |
| `connected_at`    | No       | [Timestamp](/reference/schemas/#timestamp)                      | —                                                                                                        |
| `created_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)                      | —                                                                                                        |
| `updated_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)                      | —                                                                                                        |

## PipeConnectionCreate

No description.

| Property          | Required | Type and constraints                                 | Description                                        |
| ----------------- | -------- | ---------------------------------------------------- | -------------------------------------------------- |
| `provider`        | Yes      | string (`maxLength: 64`)                             | —                                                  |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                  |
| `user_id`         | Yes      | string (`minLength: 1`; `maxLength: 256`)            | —                                                  |
| `return_url`      | Yes      | string (`maxLength: 2048`)                           | One of the environment's registered redirect URIs. |

## PipeConnectionId

No description.

string (`pattern: "^pipe_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PipeConnectionList

No description.

| Property      | Required | Type and constraints                                          | Description |
| ------------- | -------- | ------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                     | —           |
| `data`        | Yes      | Array of [PipeConnection](/reference/schemas/#pipeconnection) | —           |
| `has_more`    | Yes      | boolean                                                       | —           |
| `next_cursor` | Yes      | string or null                                                | —           |

## PipeProvider

No description.

| Property        | Required | Type and constraints                       | Description |
| --------------- | -------- | ------------------------------------------ | ----------- |
| `object`        | Yes      | string (`enum: ["pipe_provider"]`)         | —           |
| `provider`      | Yes      | string                                     | —           |
| `kind`          | Yes      | string                                     | —           |
| `client_id`     | Yes      | string                                     | —           |
| `scopes`        | Yes      | Array of string                            | —           |
| `authorize_url` | No       | string                                     | —           |
| `token_url`     | No       | string                                     | —           |
| `revoke_url`    | No       | string                                     | —           |
| `created_at`    | Yes      | [Timestamp](/reference/schemas/#timestamp) | —           |
| `updated_at`    | Yes      | [Timestamp](/reference/schemas/#timestamp) | —           |

## PipeProviderList

No description.

| Property | Required | Type and constraints                                      | Description |
| -------- | -------- | --------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`enum: ["list"]`)                                 | —           |
| `data`   | Yes      | Array of [PipeProvider](/reference/schemas/#pipeprovider) | —           |

## PipeProviderPut

No description.

| Property        | Required | Type and constraints                                                                           | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------------------- | ----------- |
| `kind`          | Yes      | string (`enum: ["github","google","slack","salesforce","hubspot","linear","notion","oauth2"]`) | —           |
| `client_id`     | Yes      | string (`minLength: 1`; `maxLength: 512`)                                                      | —           |
| `client_secret` | Yes      | string (`minLength: 1`; `maxLength: 4096`)                                                     | —           |
| `scopes`        | No       | Array of string (`maxLength: 256`)                                                             | —           |
| `authorize_url` | No       | string (`maxLength: 2048`)                                                                     | —           |
| `token_url`     | No       | string (`maxLength: 2048`)                                                                     | —           |
| `revoke_url`    | No       | string (`maxLength: 2048`)                                                                     | —           |

## Policy

No description.

| Property       | Required | Type and constraints                                   | Description |
| -------------- | -------- | ------------------------------------------------------ | ----------- |
| `id`           | Yes      | [PolicyId](/reference/schemas/#policyid)               | —           |
| `object`       | Yes      | string (`const: "policy"`)                             | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid)   | —           |
| `kind`         | Yes      | [PolicyKindValue](/reference/schemas/#policykindvalue) | —           |
| `config`       | Yes      | [PolicyConfig](/reference/schemas/#policyconfig)       | —           |
| `exclusions`   | Yes      | Array of string                                        | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                         | —           |
| `updated_at`   | Yes      | string (`format: "date-time"`)                         | —           |

## PolicyConfig

No description.

| Property                | Required | Type and constraints                                              | Description |
| ----------------------- | -------- | ----------------------------------------------------------------- | ----------- |
| `domains`               | No       | Array of string                                                   | —           |
| `max_age_seconds`       | No       | integer (`minimum: 60`; `maximum: 2592000`)                       | —           |
| `allow`                 | No       | boolean                                                           | —           |
| `verified_domain_email` | No       | boolean                                                           | —           |
| `idp_groups`            | No       | Array of string                                                   | —           |
| `scim_groups`           | No       | Array of [DirectoryGroupId](/reference/schemas/#directorygroupid) | —           |
| `rules`                 | No       | Array of [PolicyRule](/reference/schemas/#policyrule)             | —           |

## PolicyCreate

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `kind`         | Yes      | [PolicyKind](/reference/schemas/#policykind)         | —           |
| `config`       | Yes      | [PolicyConfig](/reference/schemas/#policyconfig)     | —           |
| `exclusions`   | No       | Array of string                                      | —           |

## PolicyExpression

No description.

| Property    | Required | Type and constraints                                              | Description |
| ----------- | -------- | ----------------------------------------------------------------- | ----------- |
| `kind`      | No       | string (`enum: ["leaf","all","any"]`)                             | —           |
| `attribute` | No       | string (`enum: ["email","email.domain","groups.idp"]`)            | —           |
| `operator`  | No       | string (`enum: ["equals","in","contains","contains_any"]`)        | —           |
| `values`    | No       | Array of string                                                   | —           |
| `children`  | No       | Array of [PolicyExpression](/reference/schemas/#policyexpression) | —           |

## PolicyId

No description.

string (`pattern: "^pol_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PolicyKind

No description.

string (`enum: ["force_sso","session","idp_initiated","jit","expression","guest_sso"]`)

## PolicyKindValue

A stored policy's kind. The set may grow within v1; clients ignore policies of a kind they don't know.

string

## PolicyList

No description.

| Property   | Required | Type and constraints                          | Description |
| ---------- | -------- | --------------------------------------------- | ----------- |
| `object`   | Yes      | string (`const: "list"`)                      | —           |
| `data`     | Yes      | Array of [Policy](/reference/schemas/#policy) | —           |
| `has_more` | Yes      | boolean                                       | —           |

## PolicyRule

No description.

| Property | Required | Type and constraints                                     | Description |
| -------- | -------- | -------------------------------------------------------- | ----------- |
| `action` | Yes      | string (`enum: ["allow","deny"]`)                        | —           |
| `expr`   | Yes      | [PolicyExpression](/reference/schemas/#policyexpression) | —           |

## PolicyUpdate

No description.

| Property     | Required | Type and constraints                             | Description |
| ------------ | -------- | ------------------------------------------------ | ----------- |
| `config`     | No       | [PolicyConfig](/reference/schemas/#policyconfig) | —           |
| `exclusions` | No       | Array of string                                  | —           |

## PortalFeature

No description.

string (`enum: ["sso","dsync"]`)

## PortalIDPId

No description.

string (`enum: ["okta","entra","google_workspace","onelogin","jumpcloud","adfs","generic_saml","generic_oidc","generic_scim","okta_oidc","entra_oidc","google_oidc","pingfederate","pingone","keycloak","adp","auth0","cas","classlink","clever_oidc","cloudflare_access","cyberark","duo","lastpass","login_gov","miniorange","netiq","oracle","rippling","salesforce","shibboleth","shibboleth_unsolicited","simplesamlphp","vmware","sailpoint","csv","bamboohr","rippling_hris","google_admin_sdk","sftp_csv","workday","hibob","personio","gusto"]`)

## PortalInvite

No description.

| Property          | Required | Type and constraints                                               | Description                                  |
| ----------------- | -------- | ------------------------------------------------------------------ | -------------------------------------------- |
| `completion`      | No       | [PortalSetupCompletion](/reference/schemas/#portalsetupcompletion) | —                                            |
| `profile`         | No       | [PortalProfileId](/reference/schemas/#portalprofileid)             | —                                            |
| `id`              | Yes      | [PortalInviteId](/reference/schemas/#portalinviteid)               | —                                            |
| `object`          | Yes      | string (`const: "portal_invite"`)                                  | —                                            |
| `organization_id` | No       | [OrganizationId](/reference/schemas/#organizationid)               | —                                            |
| `intents`         | No       | Array of [Intent](/reference/schemas/#intent)                      | —                                            |
| `email`           | No       | string or null                                                     | —                                            |
| `state`           | Yes      | string (`enum: ["pending","used","revoked","expired"]`)            | —                                            |
| `url`             | No       | string or null                                                     | Returned once, only when no email was given. |
| `expires_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)                         | —                                            |
| `created_at`      | No       | [Timestamp](/reference/schemas/#timestamp)                         | —                                            |

## PortalInviteCreate

No description.

| Property       | Required | Type and constraints                                   | Description                                                                              |
| -------------- | -------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `profile`      | No       | [PortalProfileId](/reference/schemas/#portalprofileid) | —                                                                                        |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid)   | —                                                                                        |
| `intents`      | Yes      | Array of [Intent](/reference/schemas/#intent)          | —                                                                                        |
| `email`        | No       | string (`format: "email"`)                             | —                                                                                        |
| `ttl`          | No       | integer (`minimum: 300`; `maximum: 604800`)            | Seconds; default and maximum 604800 (7 days).                                            |
| `single_use`   | No       | boolean                                                | Default true. When false, the invite can be opened again until it expires or is revoked. |
| `locale`       | No       | [PortalLocale](/reference/schemas/#portallocale)       | —                                                                                        |

## PortalInviteId

No description.

string (`pattern: "^pinv_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PortalInviteList

No description.

| Property      | Required | Type and constraints                                      | Description |
| ------------- | -------- | --------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                  | —           |
| `data`        | Yes      | Array of [PortalInvite](/reference/schemas/#portalinvite) | —           |
| `has_more`    | Yes      | boolean                                                   | —           |
| `next_cursor` | Yes      | string or null                                            | —           |

## PortalLink

No description.

| Property     | Required | Type and constraints                             | Description |
| ------------ | -------- | ------------------------------------------------ | ----------- |
| `id`         | Yes      | [PortalLinkId](/reference/schemas/#portallinkid) | —           |
| `object`     | Yes      | string (`const: "portal_link"`)                  | —           |
| `url`        | Yes      | string (`format: "uri"`)                         | Shown once. |
| `expires_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)       | —           |

## PortalLinkCreate

No description.

| Property       | Required | Type and constraints                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------- | -------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profile`      | No       | [PortalProfileId](/reference/schemas/#portalprofileid)            | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid)              | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `intents`      | Yes      | Array of [Intent](/reference/schemas/#intent)                     | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `return_url`   | No       | string (`format: "uri"`)                                          | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `success_urls` | No       | object (`additionalProperties: {"type":"string","format":"uri"}`) | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `connection`   | No       | [ConnectionId](/reference/schemas/#connectionid)                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `ttl`          | No       | integer (`minimum: 60`; `maximum: 300`)                           | Seconds, 60 to 300, for a sealed single-use embed link. Leave it out for a setup link, whose lifetime `expires_in` sets. Not together with `expires_in`.                                                                                                                                                                                                                                                                                                       |
| `expires_in`   | No       | integer (`minimum: 300`; `maximum: 2592000`; `default: 604800`)   | Seconds the setup link lasts, 300 (5 minutes) to 2592000 (30 days); default 604800 (7 days), the same whether the link is created through the API or in the dashboard. A link an API key creates opens once; one a member creates in the dashboard can be opened again until it ends. Both are revocable; `expires_at` says when the link ends. Outside the range, or sent with `ttl`, the request is refused with `parameter_invalid` (`param` `expires_in`). |
| `locale`       | No       | [PortalLocale](/reference/schemas/#portallocale)                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## PortalLinkId

No description.

string (`pattern: "^plink_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PortalLinkInfo

A portal link without its URL (shown once at creation).

| Property          | Required | Type and constraints                                               | Description                                                                                 |
| ----------------- | -------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `completion`      | No       | [PortalSetupCompletion](/reference/schemas/#portalsetupcompletion) | —                                                                                           |
| `profile`         | No       | [PortalProfileId](/reference/schemas/#portalprofileid)             | —                                                                                           |
| `id`              | Yes      | [PortalLinkId](/reference/schemas/#portallinkid)                   | —                                                                                           |
| `object`          | Yes      | string (`const: "portal_link"`)                                    | —                                                                                           |
| `organization_id` | Yes      | [OrganizationId](/reference/schemas/#organizationid)               | —                                                                                           |
| `intents`         | Yes      | Array of [Intent](/reference/schemas/#intent)                      | —                                                                                           |
| `state`           | Yes      | string (`enum: ["pending","used","revoked","expired"]`)            | —                                                                                           |
| `expires_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)                         | —                                                                                           |
| `created_at`      | No       | [Timestamp](/reference/schemas/#timestamp)                         | —                                                                                           |
| `opened_at`       | No       | [See the full composed schema](/spec/openapi-v1.yaml)              | When the link was first opened, for single-use and reusable links alike; absent until then. |

## PortalLinkInfoList

No description.

| Property      | Required | Type and constraints                                          | Description |
| ------------- | -------- | ------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                      | —           |
| `data`        | Yes      | Array of [PortalLinkInfo](/reference/schemas/#portallinkinfo) | —           |
| `has_more`    | Yes      | boolean                                                       | —           |
| `next_cursor` | Yes      | string or null                                                | —           |

## PortalLocale

A portal language (BCP 47): en, or one of the machine-translated de, es, fr, ja, pt-BR. Optional on a link or invite; any other value answers parameter_invalid (param locale). The set may grow within v1; clients treat an unknown value as English.

string

## PortalProfile

No description.

| Property              | Required | Type and constraints                                        | Description                              |
| --------------------- | -------- | ----------------------------------------------------------- | ---------------------------------------- |
| `name`                | Yes      | string (`minLength: 1`; `maxLength: 200`)                   | Trimmed name limited to 200 UTF-8 bytes. |
| `allowed_idps`        | Yes      | Array of [PortalIDPId](/reference/schemas/#portalidpid)     | —                                        |
| `allowed_features`    | Yes      | Array of [PortalFeature](/reference/schemas/#portalfeature) | —                                        |
| `required_attributes` | Yes      | Array of string (`minLength: 1`; `maxLength: 64`)           | —                                        |
| `id`                  | Yes      | [PortalProfileId](/reference/schemas/#portalprofileid)      | —                                        |
| `object`              | Yes      | string (`const: "portal_profile"`)                          | —                                        |
| `created_at`          | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —                                        |
| `updated_at`          | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —                                        |

## PortalProfileConfig

No description.

| Property              | Required | Type and constraints                                        | Description                              |
| --------------------- | -------- | ----------------------------------------------------------- | ---------------------------------------- |
| `name`                | Yes      | string (`minLength: 1`; `maxLength: 200`)                   | Trimmed name limited to 200 UTF-8 bytes. |
| `allowed_idps`        | Yes      | Array of [PortalIDPId](/reference/schemas/#portalidpid)     | —                                        |
| `allowed_features`    | Yes      | Array of [PortalFeature](/reference/schemas/#portalfeature) | —                                        |
| `required_attributes` | Yes      | Array of string (`minLength: 1`; `maxLength: 64`)           | —                                        |

## PortalProfileId

No description.

string (`pattern: "^pprof_[0-9A-HJKMNP-TV-Z]{26}$"`)

## PortalProfileList

No description.

| Property   | Required | Type and constraints                                        | Description |
| ---------- | -------- | ----------------------------------------------------------- | ----------- |
| `object`   | Yes      | string (`const: "list"`)                                    | —           |
| `data`     | Yes      | Array of [PortalProfile](/reference/schemas/#portalprofile) | —           |
| `has_more` | Yes      | boolean (`const: false`)                                    | —           |

## PortalSetupCompletion

No description.

| Property       | Required | Type and constraints                                        | Description |
| -------------- | -------- | ----------------------------------------------------------- | ----------- |
| `features`     | Yes      | Array of [PortalFeature](/reference/schemas/#portalfeature) | —           |
| `connection`   | No       | [ConnectionId](/reference/schemas/#connectionid)            | —           |
| `directory`    | No       | [DirectoryId](/reference/schemas/#directoryid)              | —           |
| `object`       | Yes      | string (`const: "portal_setup_completion"`)                 | —           |
| `completed_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                  | —           |

## PortalTestResult

No description.

| Property       | Required | Type and constraints                              | Description                                                                                                        |
| -------------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `attempt_id`   | No       | [SignInId](/reference/schemas/#signinid)          | The recorded test sign-in this result is about (the start call's attempt_id). Absent while nothing is recorded.    |
| `started_at`   | No       | [Timestamp](/reference/schemas/#timestamp)        | When that attempt was started (for attempts started before attempt IDs existed, when it was recorded).             |
| `tested_email` | No       | string                                            | The account the test signed in as, masked as in logs (j***@acme.com, doc 05). Absent when the IdP never named one. |
| `state`        | Yes      | string (`enum: ["pending","succeeded","failed"]`) | —                                                                                                                  |
| `checks`       | Yes      | Array of object                                   | —                                                                                                                  |
| `doctor`       | No       | [DoctorOutput](/reference/schemas/#doctoroutput)  | Connection Doctor output for a failed test (cause and IdP-specific fix steps); absent otherwise.                   |

## Profile

No description.

| Property                | Required | Type and constraints                                                                                                                                                                         | Description                                                                                                                                                                                                                                                                                         |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claims`                | No       | object (`additionalProperties: {"oneOf":[{"type":"string","maxLength":256},{"type":"boolean"},{"type":"number"},{"type":"array","maxItems":16,"items":{"type":"string","maxLength":256}}]}`) | Custom claims the environment's sign-in hook added (Business+). At most 16 claims of a string (up to 256 characters), boolean, number or list of up to 16 strings; reserved profile and token claim names are never set. Absent when no hook added any.                                             |
| `risk`                  | No       | [SignInRisk](/reference/schemas/#signinrisk)                                                                                                                                                 | —                                                                                                                                                                                                                                                                                                   |
| `custom_attributes`     | No       | [CustomAttributeValues](/reference/schemas/#customattributevalues)                                                                                                                           | —                                                                                                                                                                                                                                                                                                   |
| `policy_hints`          | No       | [ProfilePolicyHints](/reference/schemas/#profilepolicyhints)                                                                                                                                 | —                                                                                                                                                                                                                                                                                                   |
| `access_policy`         | No       | string (`enum: ["guest"]`)                                                                                                                                                                   | Set to `guest` only when the sign-in was admitted under the organization's guest policy (a guest_sso policy, from an email domain outside the organization's verified domains). Absent for every other sign-in. `email_domain_verified` stays `true` for guests; use this field to tell them apart. |
| `email_verified`        | No       | boolean                                                                                                                                                                                      | —                                                                                                                                                                                                                                                                                                   |
| `idp_groups_verified`   | No       | boolean                                                                                                                                                                                      | —                                                                                                                                                                                                                                                                                                   |
| `id`                    | Yes      | [ProfileId](/reference/schemas/#profileid)                                                                                                                                                   | —                                                                                                                                                                                                                                                                                                   |
| `object`                | Yes      | string (`const: "profile"`)                                                                                                                                                                  | —                                                                                                                                                                                                                                                                                                   |
| `organization_id`       | Yes      | [OrganizationId](/reference/schemas/#organizationid)                                                                                                                                         | —                                                                                                                                                                                                                                                                                                   |
| `connection_id`         | Yes      | [ConnectionId](/reference/schemas/#connectionid)                                                                                                                                             | —                                                                                                                                                                                                                                                                                                   |
| `connection_type`       | Yes      | string (`enum: ["saml","oidc"]`)                                                                                                                                                             | —                                                                                                                                                                                                                                                                                                   |
| `idp_id`                | Yes      | string                                                                                                                                                                                       | —                                                                                                                                                                                                                                                                                                   |
| `email`                 | Yes      | string (`format: "email"`)                                                                                                                                                                   | —                                                                                                                                                                                                                                                                                                   |
| `email_domain_verified` | Yes      | boolean (`const: true`)                                                                                                                                                                      | —                                                                                                                                                                                                                                                                                                   |
| `first_name`            | No       | string or null                                                                                                                                                                               | —                                                                                                                                                                                                                                                                                                   |
| `last_name`             | No       | string or null                                                                                                                                                                               | —                                                                                                                                                                                                                                                                                                   |
| `groups`                | No       | Array of string                                                                                                                                                                              | —                                                                                                                                                                                                                                                                                                   |
| `role`                  | No       | string or null                                                                                                                                                                               | —                                                                                                                                                                                                                                                                                                   |
| `attributes`            | No       | object (`additionalProperties: true`)                                                                                                                                                        | —                                                                                                                                                                                                                                                                                                   |
| `raw_attributes`        | No       | object (`additionalProperties: true`)                                                                                                                                                        | —                                                                                                                                                                                                                                                                                                   |
| `legacy_ids`            | No       | object (`additionalProperties: {"type":"string"}`)                                                                                                                                           | Imported provider profile IDs for this connection and IdP subject, carried through the broker token, profile and forwarded responses without a database read.                                                                                                                                       |

## ProfileId

Deterministic: HMAC(connection_id, idp_subject), identical in every cell (doc 02 section 4).

string (`pattern: "^prof_[0-9A-Za-z]{16,64}$"`)

## ProfilePolicyHints

No description.

| Property                | Required | Type and constraints | Description                                                                                                                                                        |
| ----------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `force_sso`             | No       | boolean              | —                                                                                                                                                                  |
| `force_sso_excluded`    | No       | boolean              | —                                                                                                                                                                  |
| `max_age_seconds`       | No       | integer              | —                                                                                                                                                                  |
| `idp_initiated_allowed` | No       | boolean              | —                                                                                                                                                                  |
| `guest`                 | No       | boolean              | Admitted by a guest_sso policy from a domain outside the organization's verified domains; require SSO and do not link the user by email outside this organization. |

## ProjectId

No description.

string (`pattern: "^proj_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ProviderAttributes

Attribute or claim names the provider sends by default; an absent key has no default and is mapped explicitly.

| Property     | Required | Type and constraints | Description |
| ------------ | -------- | -------------------- | ----------- |
| `email`      | No       | string               | —           |
| `first_name` | No       | string               | —           |
| `last_name`  | No       | string               | —           |
| `groups`     | No       | string               | —           |

## ProviderAvailability

`available`: new directories of the source may be created. `coming_soon`: listed so it can be shown, but new directories are refused with `provider_coming_soon` (existing ones keep syncing); interest can be registered instead. Set per environment. New values may be added.

string (`enum: ["available","coming_soon"]`)

## ProviderCatalogue

No description.

| Property      | Required | Type and constraints                                                            | Description |
| ------------- | -------- | ------------------------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "provider_catalogue"`)                                          | —           |
| `sso`         | Yes      | Array of [SSOProvider](/reference/schemas/#ssoprovider)                         | —           |
| `directories` | Yes      | Array of [DirectorySourceProvider](/reference/schemas/#directorysourceprovider) | —           |

## ProviderQuirk

A known provider behaviour the setup accounts for. New values may be added.

string

## RadarAlertSubscription

No description.

| Property     | Required | Type and constraints                                      | Description |
| ------------ | -------- | --------------------------------------------------------- | ----------- |
| `object`     | Yes      | string (`const: "radar_alert_subscription"`)              | —           |
| `email`      | Yes      | string (`format: "email"`)                                | —           |
| `idps`       | Yes      | Array of [RadarIdpType](/reference/schemas/#radaridptype) | —           |
| `created_at` | Yes      | string (`format: "date-time"`)                            | —           |

## RadarAlertSubscriptionPut

No description.

| Property | Required | Type and constraints                                         | Description |
| -------- | -------- | ------------------------------------------------------------ | ----------- |
| `email`  | Yes      | string (`format: "email"`; `minLength: 3`; `maxLength: 254`) | —           |
| `idps`   | No       | Array of [RadarIdpType](/reference/schemas/#radaridptype)    | —           |

## RadarIdpType

No description.

string (`enum: ["okta","entra","google","onelogin","jumpcloud","ping","adfs","other"]`)

## RedirectUri

No description.

| Property     | Required | Type and constraints                               | Description |
| ------------ | -------- | -------------------------------------------------- | ----------- |
| `id`         | Yes      | [RedirectUriId](/reference/schemas/#redirecturiid) | —           |
| `object`     | Yes      | string (`const: "redirect_uri"`)                   | —           |
| `uri`        | Yes      | string (`format: "uri"`)                           | —           |
| `created_at` | No       | [Timestamp](/reference/schemas/#timestamp)         | —           |

## RedirectUriCreate

No description.

| Property | Required | Type and constraints     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uri`    | Yes      | string (`format: "uri"`) | Exact match. An absolute https URL; `http://localhost` (or another loopback host) in sandbox environments only; or, for native apps, a reverse-domain private-use scheme such as `com.example.app:/oauth/callback` (RFC 8252 §7.1: lowercase, at least one dot, a path, no authority, user info or fragment). javascript:, data:, file:, vbscript: and single-word schemes are refused. Sign-in from a publishable key always requires PKCE S256. |

## RedirectUriId

No description.

string (`pattern: "^ruri_[0-9A-HJKMNP-TV-Z]{26}$"`)

## RedirectUriList

No description.

| Property      | Required | Type and constraints                                    | Description |
| ------------- | -------- | ------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                | —           |
| `data`        | Yes      | Array of [RedirectUri](/reference/schemas/#redirecturi) | —           |
| `has_more`    | Yes      | boolean                                                 | —           |
| `next_cursor` | Yes      | string or null                                          | —           |

## RequestId

No description.

string (`pattern: "^req_[0-9A-HJKMNP-TV-Z]{26}$"`)

## RequestLog

No description.

| Property          | Required | Type and constraints                                 | Description                                                                   |
| ----------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
| `id`              | Yes      | [RequestId](/reference/schemas/#requestid)           | —                                                                             |
| `object`          | Yes      | string (`const: "request"`)                          | —                                                                             |
| `method`          | Yes      | string                                               | —                                                                             |
| `path`            | Yes      | string                                               | The route template (e.g. `/v1/organizations/{org}`), never the concrete path. |
| `status`          | Yes      | integer                                              | —                                                                             |
| `api_key_id`      | No       | [ApiKeyId](/reference/schemas/#apikeyid)             | The API key of the call; absent for dashboard, CLI and portal sessions.       |
| `organization_id` | No       | [OrganizationId](/reference/schemas/#organizationid) | The organization the route names, when it names one.                          |
| `duration_ms`     | No       | integer                                              | —                                                                             |
| `request_id`      | No       | string                                               | The `Request-Id` header of the response.                                      |
| `created_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)           | —                                                                             |

## RequestLogList

No description.

| Property      | Required | Type and constraints                                  | Description |
| ------------- | -------- | ----------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                              | —           |
| `data`        | Yes      | Array of [RequestLog](/reference/schemas/#requestlog) | —           |
| `has_more`    | Yes      | boolean                                               | —           |
| `next_cursor` | Yes      | string or null                                        | —           |

## ResidencyPlacement

No description.

| Property        | Required | Type and constraints                                   | Description                                                                   |
| --------------- | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `data_class`    | Yes      | string                                                 | Stable name of the data class, for example `directory_users` or `audit_logs`. |
| `description`   | Yes      | string                                                 | —                                                                             |
| `scope`         | Yes      | string (`enum: ["home_region","global"]`)              | —                                                                             |
| `region`        | No       | [ResidencyRegion](/reference/schemas/#residencyregion) | The home region; present only when `scope` is `home_region`.                  |
| `personal_data` | Yes      | boolean                                                | —                                                                             |

## ResidencyRegion

Data residency region. Chosen when the environment is created and fixed afterwards; only OhAuthCat staff can move an environment, through an audited migration. Defaults to the region of the cell that serves the request. Only regions this deployment runs are accepted; choosing a region other than the default needs the Enterprise plan (`plan_limit_reached` otherwise).

string (`enum: ["eu","in","us"]`)

## Role

No description.

| Property       | Required | Type and constraints                                          | Description                                                                                     |
| -------------- | -------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `id`           | Yes      | [RoleId](/reference/schemas/#roleid)                          | —                                                                                               |
| `object`       | Yes      | string (`const: "role"`)                                      | —                                                                                               |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid)          | —                                                                                               |
| `slug`         | Yes      | [MembershipRole](/reference/schemas/#membershiprole)          | —                                                                                               |
| `name`         | No       | string (`maxLength: 200`)                                     | —                                                                                               |
| `description`  | No       | string (`maxLength: 1000`)                                    | —                                                                                               |
| `priority`     | Yes      | integer (`minimum: 0`; `maximum: 10000`)                      | Higher wins. The highest-priority role is a membership's primary role (the `role` token claim). |
| `permissions`  | Yes      | Array of [PermissionSlug](/reference/schemas/#permissionslug) | —                                                                                               |
| `created_at`   | Yes      | string (`format: "date-time"`)                                | —                                                                                               |
| `updated_at`   | Yes      | string (`format: "date-time"`)                                | —                                                                                               |

## RoleAssignment

No description.

| Property     | Required | Type and constraints                                     | Description |
| ------------ | -------- | -------------------------------------------------------- | ----------- |
| `id`         | Yes      | [RoleAssignmentId](/reference/schemas/#roleassignmentid) | —           |
| `object`     | Yes      | string (`const: "role_assignment"`)                      | —           |
| `membership` | Yes      | [MembershipId](/reference/schemas/#membershipid)         | —           |
| `role`       | Yes      | [MembershipRole](/reference/schemas/#membershiprole)     | —           |
| `role_id`    | No       | [RoleId](/reference/schemas/#roleid)                     | —           |
| `resource`   | No       | [AuthzResource](/reference/schemas/#authzresource)       | —           |
| `source`     | Yes      | string (`enum: ["api","sso"]`)                           | —           |
| `created_at` | Yes      | string (`format: "date-time"`)                           | —           |

## RoleAssignmentCreate

No description.

| Property   | Required | Type and constraints                                 | Description |
| ---------- | -------- | ---------------------------------------------------- | ----------- |
| `role`     | Yes      | [MembershipRole](/reference/schemas/#membershiprole) | —           |
| `resource` | No       | [AuthzResource](/reference/schemas/#authzresource)   | —           |

## RoleAssignmentId

No description.

string (`pattern: "^rasn_[0-9A-HJKMNP-TV-Z]{26}$"`)

## RoleAssignmentList

No description.

| Property      | Required | Type and constraints                                          | Description |
| ------------- | -------- | ------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                      | —           |
| `data`        | Yes      | Array of [RoleAssignment](/reference/schemas/#roleassignment) | —           |
| `has_more`    | Yes      | boolean                                                       | —           |
| `next_cursor` | Yes      | string or null                                                | —           |

## RoleCreate

No description.

| Property       | Required | Type and constraints                                          | Description |
| -------------- | -------- | ------------------------------------------------------------- | ----------- |
| `slug`         | Yes      | [MembershipRole](/reference/schemas/#membershiprole)          | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid)          | —           |
| `name`         | No       | string (`maxLength: 200`)                                     | —           |
| `description`  | No       | string (`maxLength: 1000`)                                    | —           |
| `priority`     | No       | integer (`minimum: 0`; `maximum: 10000`)                      | —           |
| `permissions`  | No       | Array of [PermissionSlug](/reference/schemas/#permissionslug) | —           |

## RoleId

No description.

string (`pattern: "^role_[0-9A-HJKMNP-TV-Z]{26}$"`)

## RoleList

No description.

| Property      | Required | Type and constraints                      | Description |
| ------------- | -------- | ----------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                  | —           |
| `data`        | Yes      | Array of [Role](/reference/schemas/#role) | —           |
| `has_more`    | Yes      | boolean                                   | —           |
| `next_cursor` | Yes      | string or null                            | —           |

## RoleRule

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `id`           | Yes      | [RoleRuleId](/reference/schemas/#roleruleid)         | —           |
| `object`       | Yes      | string (`const: "role_rule"`)                        | —           |
| `organization` | No       | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `kind`         | Yes      | [RoleRuleKind](/reference/schemas/#rolerulekind)     | —           |
| `match`        | Yes      | [RoleRuleMatch](/reference/schemas/#rolerulematch)   | —           |
| `role`         | Yes      | string                                               | —           |
| `priority`     | Yes      | integer (`format: "int64"`)                          | —           |
| `condition`    | No       | [PolicyRule](/reference/schemas/#policyrule)         | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                       | —           |
| `updated_at`   | Yes      | string (`format: "date-time"`)                       | —           |

## RoleRuleCondition

No description.

| Property | Required | Type and constraints                                     | Description |
| -------- | -------- | -------------------------------------------------------- | ----------- |
| `action` | Yes      | string (`enum: ["allow","deny"]`)                        | —           |
| `expr`   | Yes      | [PolicyExpression](/reference/schemas/#policyexpression) | —           |

## RoleRuleCreate

No description.

| Property       | Required | Type and constraints                                       | Description |
| -------------- | -------- | ---------------------------------------------------------- | ----------- |
| `organization` | No       | string (`pattern: "^org_[0-9A-HJKMNP-TV-Z]{26}$"`)         | —           |
| `kind`         | Yes      | string (`enum: ["group","domain","connection"]`)           | —           |
| `match`        | Yes      | [RoleRuleMatch](/reference/schemas/#rolerulematch)         | —           |
| `role`         | Yes      | string (`minLength: 1`; `maxLength: 128`)                  | —           |
| `priority`     | Yes      | integer (`format: "int64"`)                                | —           |
| `condition`    | No       | [RoleRuleCondition](/reference/schemas/#rolerulecondition) | —           |

## RoleRuleId

No description.

string (`pattern: "^rrule_[0-9A-HJKMNP-TV-Z]{26}$"`)

## RoleRuleKind

No description.

string (`enum: ["group","domain","connection"]`)

## RoleRuleList

No description.

| Property   | Required | Type and constraints                              | Description |
| ---------- | -------- | ------------------------------------------------- | ----------- |
| `object`   | Yes      | string (`const: "list"`)                          | —           |
| `data`     | Yes      | Array of [RoleRule](/reference/schemas/#rolerule) | —           |
| `has_more` | Yes      | boolean                                           | —           |

## RoleRuleMatch

No description.

| Property     | Required | Type and constraints                                | Description |
| ------------ | -------- | --------------------------------------------------- | ----------- |
| `idp_group`  | No       | string (`maxLength: 256`)                           | —           |
| `scim_group` | No       | string (`pattern: "^dgrp_[0-9A-HJKMNP-TV-Z]{26}$"`) | —           |
| `domain`     | No       | string (`maxLength: 253`)                           | —           |
| `connection` | No       | string (`pattern: "^conn_[0-9A-HJKMNP-TV-Z]{26}$"`) | —           |

## RoleRulePreview

No description.

| Property | Required | Type and constraints                  | Description                                       |
| -------- | -------- | ------------------------------------- | ------------------------------------------------- |
| `object` | Yes      | string (`const: "role_rule_preview"`) | —                                                 |
| `role`   | Yes      | string or null                        | The assigned role; null when no rule assigns one. |
| `denied` | Yes      | boolean                               | —                                                 |

## RoleRulePreviewRequest

No description.

| Property              | Required | Type and constraints                                              | Description |
| --------------------- | -------- | ----------------------------------------------------------------- | ----------- |
| `organization`        | Yes      | [OrganizationId](/reference/schemas/#organizationid)              | —           |
| `connection`          | Yes      | [ConnectionId](/reference/schemas/#connectionid)                  | —           |
| `email`               | No       | string (`maxLength: 320`)                                         | —           |
| `email_verified`      | No       | boolean                                                           | —           |
| `idp_groups`          | No       | Array of string (`minLength: 1`; `maxLength: 256`)                | —           |
| `idp_groups_verified` | No       | boolean                                                           | —           |
| `scim_groups`         | No       | Array of [DirectoryGroupId](/reference/schemas/#directorygroupid) | —           |
| `draft`               | No       | [RoleRuleCreate](/reference/schemas/#rolerulecreate)              | —           |

## RoleRuleUpdate

No description.

| Property          | Required | Type and constraints                                       | Description |
| ----------------- | -------- | ---------------------------------------------------------- | ----------- |
| `match`           | No       | [RoleRuleMatch](/reference/schemas/#rolerulematch)         | —           |
| `role`            | No       | string (`minLength: 1`; `maxLength: 128`)                  | —           |
| `priority`        | No       | integer (`format: "int64"`)                                | —           |
| `clear_condition` | No       | boolean                                                    | —           |
| `condition`       | No       | [RoleRuleCondition](/reference/schemas/#rolerulecondition) | —           |

## RoleUpdate

No description.

| Property      | Required | Type and constraints                                          | Description                      |
| ------------- | -------- | ------------------------------------------------------------- | -------------------------------- |
| `name`        | No       | string or null (`maxLength: 200`)                             | —                                |
| `description` | No       | string or null (`maxLength: 1000`)                            | —                                |
| `priority`    | No       | integer (`minimum: 0`; `maximum: 10000`)                      | —                                |
| `permissions` | No       | Array of [PermissionSlug](/reference/schemas/#permissionslug) | Replaces the role's permissions. |

## SPKeyRotation

No description.

| Property           | Required | Type and constraints                                                                                                                                                   | Description |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `object`           | Yes      | string (`const: "sp_key_rotation"`)                                                                                                                                    | —           |
| `connection`       | Yes      | [ConnectionId](/reference/schemas/#connectionid)                                                                                                                       | —           |
| `generation`       | Yes      | [SPKeyRotationGeneration](/reference/schemas/#spkeyrotationgeneration)                                                                                                 | —           |
| `state`            | Yes      | string (`enum: ["staged","activated","rolled_back","retired"]`)                                                                                                        | —           |
| `current_key`      | Yes      | [SPKeyRotationPublicKey](/reference/schemas/#spkeyrotationpublickey)                                                                                                   | —           |
| `previous_key`     | Yes      | [SPKeyRotationPublicKey](/reference/schemas/#spkeyrotationpublickey)                                                                                                   | —           |
| `next_key`         | Yes      | [SPKeyRotationPublicKey](/reference/schemas/#spkeyrotationpublickey)                                                                                                   | —           |
| `pending_reasons`  | Yes      | Array of string (`enum: ["notice_required","notice_wait","test_required","test_failed","confirmation_required","retirement_overdue","retirement_status_unavailable"]`) | —           |
| `doctor`           | No       | [DoctorOutput](/reference/schemas/#doctoroutput)                                                                                                                       | —           |
| `test`             | No       | [SPKeyRotationTestProof](/reference/schemas/#spkeyrotationtestproof)                                                                                                   | —           |
| `acknowledged_at`  | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `test_eligible_at` | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `submission`       | No       | [SPKeyRotationSubmission](/reference/schemas/#spkeyrotationsubmission)                                                                                                 | —           |
| `confirmed_at`     | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `activated_at`     | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `rolled_back_at`   | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `retired_at`       | No       | string (`format: "date-time"`)                                                                                                                                         | —           |
| `created_at`       | Yes      | string (`format: "date-time"`)                                                                                                                                         | —           |
| `updated_at`       | Yes      | string (`format: "date-time"`)                                                                                                                                         | —           |

## SPKeyRotationAction

No description.

| Property     | Required | Type and constraints                                                   | Description |
| ------------ | -------- | ---------------------------------------------------------------------- | ----------- |
| `generation` | Yes      | [SPKeyRotationGeneration](/reference/schemas/#spkeyrotationgeneration) | —           |

## SPKeyRotationGeneration

Canonical decimal signed 64-bit generation; strings preserve precision in every client.

string (`pattern: "^[1-9][0-9]{0,18}$"`)

## SPKeyRotationPublicKey

No description.

| Property      | Required | Type and constraints                     | Description |
| ------------- | -------- | ---------------------------------------- | ----------- |
| `id`          | Yes      | string (`pattern: "^spk_[0-9a-f]{32}$"`) | —           |
| `key_id`      | Yes      | string (`pattern: "^[0-9a-f]{16}$"`)     | —           |
| `certificate` | Yes      | string (`minLength: 1`)                  | —           |

## SPKeyRotationSchedule

The server chooses fresh key material and the connection's current key.

object (`additionalProperties: false`)

## SPKeyRotationSubmission

Provider submission accounting only; successful notice requires the organization's authorized IT-admin acknowledgement. No recipient or provider details are exposed.

| Property    | Required | Type and constraints                      | Description |
| ----------- | -------- | ----------------------------------------- | ----------- |
| `requested` | Yes      | integer (`format: "int64"`; `minimum: 0`) | —           |
| `pending`   | Yes      | integer (`format: "int64"`; `minimum: 0`) | —           |
| `submitted` | Yes      | integer (`format: "int64"`; `minimum: 0`) | —           |
| `uncertain` | Yes      | integer (`format: "int64"`; `minimum: 0`) | —           |
| `skipped`   | Yes      | integer (`format: "int64"`; `minimum: 0`) | —           |

## SPKeyRotationTest

No description.

| Property     | Required | Type and constraints                                                   | Description |
| ------------ | -------- | ---------------------------------------------------------------------- | ----------- |
| `object`     | Yes      | string (`const: "sp_key_rotation_test"`)                               | —           |
| `generation` | Yes      | [SPKeyRotationGeneration](/reference/schemas/#spkeyrotationgeneration) | —           |
| `test_url`   | Yes      | string (`format: "uri"`)                                               | —           |
| `expires_at` | Yes      | string (`format: "date-time"`)                                         | —           |

## SPKeyRotationTestProof

No description.

| Property      | Required | Type and constraints                                                   | Description |
| ------------- | -------- | ---------------------------------------------------------------------- | ----------- |
| `sign_in_id`  | Yes      | [SignInId](/reference/schemas/#signinid)                               | —           |
| `generation`  | Yes      | [SPKeyRotationGeneration](/reference/schemas/#spkeyrotationgeneration) | —           |
| `sp_key_id`   | Yes      | string (`pattern: "^spk_[0-9a-f]{32}$"`)                               | —           |
| `verified_at` | Yes      | string (`format: "date-time"`)                                         | —           |

## SSOProvider

No description.

| Property          | Required | Type and constraints                                        | Description                                                                                                     |
| ----------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `id`              | Yes      | string                                                      | The catalogue ID; also the connection's `catalogue_idp` when `portal_idp` is set.                               |
| `name`            | Yes      | string                                                      | —                                                                                                               |
| `portal_idp`      | No       | [PortalIDPId](/reference/schemas/#portalidpid)              | —                                                                                                               |
| `protocols`       | Yes      | Array of string (`enum: ["saml","oidc"]`)                   | —                                                                                                               |
| `saml`            | No       | [SSOProviderSAML](/reference/schemas/#ssoprovidersaml)      | —                                                                                                               |
| `oidc`            | No       | [SSOProviderOIDC](/reference/schemas/#ssoprovideroidc)      | —                                                                                                               |
| `discovery_hosts` | Yes      | Array of string                                             | Host suffixes of the provider's IdP URLs, used to suggest this entry from an entity ID, issuer or metadata URL. |
| `quirks`          | Yes      | Array of [ProviderQuirk](/reference/schemas/#providerquirk) | —                                                                                                               |

## SSOProviderOIDC

No description.

| Property         | Required | Type and constraints                                                                     | Description                                                                            |
| ---------------- | -------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `issuer_pattern` | No       | string                                                                                   | Issuer with {placeholders}; discovery is at {issuer}/.well-known/openid-configuration. |
| `client_auth`    | Yes      | Array of string (`enum: ["client_secret_basic","client_secret_post","private_key_jwt"]`) | —                                                                                      |
| `scopes`         | Yes      | Array of string                                                                          | —                                                                                      |
| `acr_values`     | No       | Array of string                                                                          | —                                                                                      |
| `claims`         | Yes      | [ProviderAttributes](/reference/schemas/#providerattributes)                             | —                                                                                      |

## SSOProviderSAML

No description.

| Property               | Required | Type and constraints                                         | Description                                                                        |
| ---------------------- | -------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `metadata_url_pattern` | No       | string                                                       | Metadata URL with {placeholders}; absent when the provider only offers a download. |
| `name_id_format`       | Yes      | string                                                       | —                                                                                  |
| `attributes`           | Yes      | [ProviderAttributes](/reference/schemas/#providerattributes) | —                                                                                  |

## SandboxCreate

No description.

| Property          | Required | Type and constraints                                                        | Description                                                                                                                                                                                                                                                                   |
| ----------------- | -------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `turnstile_token` | Yes      | string (`minLength: 1`; `maxLength: 2048`)                                  | —                                                                                                                                                                                                                                                                             |
| `handoff_id`      | No       | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`) | The handoff from createSandboxHandoff (the `#handoff=` fragment of its `browser_url`). With it, the keys and claim URL are sealed into the handoff for the CLI and the response is SandboxHandedOff; an expired, used or unknown handoff answers 410 sandbox_handoff_expired. |

## SandboxCreated

No description.

| Property          | Required | Type and constraints                               | Description |
| ----------------- | -------- | -------------------------------------------------- | ----------- |
| `environment`     | Yes      | [EnvironmentId](/reference/schemas/#environmentid) | —           |
| `secret_key`      | Yes      | string (`pattern: "^sk_test_[0-9A-Za-z]{43}$"`)    | —           |
| `publishable_key` | Yes      | string (`pattern: "^pk_test_[0-9A-Za-z]{43}$"`)    | —           |
| `claim_url`       | Yes      | string (`format: "uri"`)                           | —           |
| `expires_at`      | Yes      | string (`format: "date-time"`)                     | —           |

## SandboxHandedOff

No description.

| Property     | Required | Type and constraints           | Description                         |
| ------------ | -------- | ------------------------------ | ----------------------------------- |
| `handed_off` | Yes      | boolean (`enum: [true]`)       | —                                   |
| `expires_at` | Yes      | string (`format: "date-time"`) | When the unclaimed sandbox expires. |

## SandboxHandoff

No description.

| Property      | Required | Type and constraints                                                        | Description                                                             |
| ------------- | -------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `handoff_id`  | Yes      | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`) | —                                                                       |
| `browser_url` | Yes      | string (`format: "uri"`)                                                    | The page that creates the sandbox; the handoff is in the fragment only. |
| `expires_in`  | Yes      | integer                                                                     | Seconds until the handoff expires.                                      |
| `interval`    | Yes      | integer                                                                     | Minimum seconds between redeem polls.                                   |

## SandboxHandoffCreate

No description.

| Property                | Required | Type and constraints                                                        | Description                                                        |
| ----------------------- | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `code_challenge`        | Yes      | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`) | BASE64URL(SHA-256(code_verifier)) without padding (RFC 7636 §4.2). |
| `code_challenge_method` | Yes      | string (`enum: ["S256"]`)                                                   | —                                                                  |

## SandboxHandoffRedeem

No description.

| Property        | Required | Type and constraints                                                               | Description |
| --------------- | -------- | ---------------------------------------------------------------------------------- | ----------- |
| `handoff_id`    | Yes      | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`)        | —           |
| `code_verifier` | Yes      | string (`minLength: 43`; `maxLength: 128`; `pattern: "^[A-Za-z0-9._~-]{43,128}$"`) | —           |

## ScimReplay

No description.

| Property      | Required | Type and constraints                                          | Description                                                                            |
| ------------- | -------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `object`      | Yes      | string (`const: "scim_replay"`)                               | —                                                                                      |
| `directory`   | Yes      | [DirectoryId](/reference/schemas/#directoryid)                | —                                                                                      |
| `idp`         | Yes      | string                                                        | —                                                                                      |
| `outcome`     | Yes      | string (`enum: ["passed","failed"]`)                          | —                                                                                      |
| `steps`       | Yes      | Array of [ScimReplayStep](/reference/schemas/#scimreplaystep) | The steps sent, in order; a failed replay stops at its last step.                      |
| `total_steps` | Yes      | integer                                                       | —                                                                                      |
| `failure`     | Yes      | string or null                                                | Why the replay stopped (no response bodies, tokens or user data); null when it passed. |
| `created_at`  | Yes      | string (`format: "date-time"`)                                | —                                                                                      |

## ScimReplayRequest

No description.

| Property | Required | Type and constraints                                                        | Description                                                                                                                                             |
| -------- | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idp`    | Yes      | string (`enum: ["generic","okta","entra","google","onelogin","jumpcloud"]`) | The test IdP flavor profile whose SCIM sequence is replayed.                                                                                            |
| `token`  | Yes      | string (`minLength: 1`; `maxLength: 256`)                                   | The directory's current SCIM bearer token (shown once on create and rotate). It is checked against the directory before anything is sent.               |
| `domain` | No       | string (`minLength: 1`; `maxLength: 128`; `pattern: "^[A-Za-z0-9.-]+$"`)    | Email domain of the test users (`alice@&lt;domain&gt;`); a verified domain of the directory's organization keeps them in domain. Default `example.com`. |

## ScimReplayStep

No description.

| Property | Required | Type and constraints | Description                                                        |
| -------- | -------- | -------------------- | ------------------------------------------------------------------ |
| `name`   | Yes      | string               | —                                                                  |
| `method` | Yes      | string               | —                                                                  |
| `status` | Yes      | integer              | HTTP status of the SCIM server's answer; 0 when no answer arrived. |
| `passed` | Yes      | boolean              | —                                                                  |

## ScimRequest

No description.

| Property                | Required | Type and constraints                               | Description |
| ----------------------- | -------- | -------------------------------------------------- | ----------- |
| `id`                    | Yes      | [ScimRequestId](/reference/schemas/#scimrequestid) | —           |
| `object`                | Yes      | string (`const: "scim_request"`)                   | —           |
| `method`                | Yes      | string                                             | —           |
| `path`                  | Yes      | string                                             | —           |
| `status`                | Yes      | integer                                            | —           |
| `error_code`            | No       | string or null                                     | —           |
| `request_body_redacted` | No       | string or null                                     | —           |
| `created_at`            | Yes      | [Timestamp](/reference/schemas/#timestamp)         | —           |

## ScimRequestId

No description.

string (`pattern: "^scrq_[0-9A-HJKMNP-TV-Z]{26}$"`)

## ScimRequestList

No description.

| Property      | Required | Type and constraints                                    | Description |
| ------------- | -------- | ------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                | —           |
| `data`        | Yes      | Array of [ScimRequest](/reference/schemas/#scimrequest) | —           |
| `has_more`    | Yes      | boolean                                                 | —           |
| `next_cursor` | Yes      | string or null                                          | —           |

## SessionMigrateRequest

No description.

| Property            | Required | Type and constraints                     | Description |
| ------------------- | -------- | ---------------------------------------- | ----------- |
| `import`            | Yes      | [ImportId](/reference/schemas/#importid) | —           |
| `legacy_profile_id` | Yes      | string (`minLength: 1`)                  | —           |

## SessionMigrateResult

No description.

| Property  | Required | Type and constraints                   | Description |
| --------- | -------- | -------------------------------------- | ----------- |
| `profile` | Yes      | [Profile](/reference/schemas/#profile) | —           |

## SignIn

No description.

| Property        | Required | Type and constraints                                       | Description                                                                                                                                                                                                                                                                                       |
| --------------- | -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | Yes      | [SignInId](/reference/schemas/#signinid)                   | —                                                                                                                                                                                                                                                                                                 |
| `object`        | Yes      | string (`const: "sign_in"`)                                | —                                                                                                                                                                                                                                                                                                 |
| `connection_id` | No       | [ConnectionId](/reference/schemas/#connectionid)           | —                                                                                                                                                                                                                                                                                                 |
| `status`        | Yes      | string (`enum: ["succeeded","failed"]`)                    | —                                                                                                                                                                                                                                                                                                 |
| `email`         | No       | string or null                                             | Redacted in logs. A succeeded sign-in carries the profile's email; a failed one carries only a masked address (j***@acme.com), and only when the identity provider's assertion was validated and then refused by a policy (email_outside_verified_domain, sign_in_policy_denied); otherwise null. |
| `error_code`    | No       | string or null                                             | —                                                                                                                                                                                                                                                                                                 |
| `created_at`    | Yes      | [Timestamp](/reference/schemas/#timestamp)                 | —                                                                                                                                                                                                                                                                                                 |
| `test`          | No       | boolean                                                    | True for a test sign-in (listed only with `include_test=true`); absent for a real one.                                                                                                                                                                                                            |
| `risk`          | No       | [SignInRiskSummary](/reference/schemas/#signinrisksummary) | The risk assessment of the sign-in when a risk policy was on and a signal fired (score 0-100 and catalog reasons; never an address, location or device). Absent otherwise.                                                                                                                        |
| `access_policy` | No       | string or null (`enum: ["member","guest",null]`)           | How the organization admitted the sign-in (D183): `member` for an email on one of its verified domains, `guest` under its `guest_sso` policy. Null for a refused sign-in, a test sign-in and sign-ins recorded before 2026-11-07.                                                                 |

## SignInExplanation

An explanation of a failed sign-in (CORE-388).

| Property             | Required | Type and constraints                                                                      | Description                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | -------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sign_in_id`         | Yes      | string or null                                                                            | The explained sign-in; null when the connection has no test sign-in yet.                                                                                                                                                                                                                                                                         |
| `error_code`         | Yes      | string or null                                                                            | The catalog code of the failure; null when the sign-in did not fail.                                                                                                                                                                                                                                                                             |
| `source`             | Yes      | string (`enum: ["doctor","provider"]`)                                                    | `provider` when a configured language model wrote the text; `doctor` for the deterministic Doctor text.                                                                                                                                                                                                                                          |
| `provider`           | Yes      | string or null                                                                            | The provider name when `source` is `provider`.                                                                                                                                                                                                                                                                                                   |
| `model`              | No       | string or null (`maxLength: 200`)                                                         | The language model that wrote the text when `source` is `provider` and the provider reports one; null otherwise.                                                                                                                                                                                                                                 |
| `unavailable_reason` | No       | string or null (`enum: ["explanation_budget_exhausted","explanation_rate_limited",null]`) | Why the language model was not asked and the Doctor text is served instead (`source` is `doctor`). `explanation_budget_exhausted` when the environment's monthly explanation cost cap is reached; `explanation_rate_limited` when too many explanations were asked for in a short window. Null otherwise (also when `explain_enabled` is false). |
| `explain_enabled`    | No       | boolean                                                                                   | False when the app's account has not turned explanations on; the provider was not asked and `source` is `doctor`.                                                                                                                                                                                                                                |
| `text`               | Yes      | string (`maxLength: 4000`)                                                                | —                                                                                                                                                                                                                                                                                                                                                |

## SignInHook

A developer sign-in hook (CORE-384). Requests carry `OhAuthCat-Signature` (the webhook scheme) and `OhAuthCat-Hook-Call-Id`; a `pre_profile_issue` answer must be HTTP 200 JSON with `call_id` (the request's), `decision` (`allow` or `deny`), an optional `reason` and optional `claims`, signed the same way with the same secret, within the timeout and 8 KiB.

| Property     | Required | Type and constraints                                                   | Description |
| ------------ | -------- | ---------------------------------------------------------------------- | ----------- |
| `id`         | Yes      | [SignInHookId](/reference/schemas/#signinhookid)                       | —           |
| `object`     | Yes      | object (`const: "sign_in_hook"`)                                       | —           |
| `point`      | Yes      | [SignInHookPointValue](/reference/schemas/#signinhookpointvalue)       | —           |
| `url`        | Yes      | string (`format: "uri"`; `maxLength: 2048`)                            | —           |
| `fail_mode`  | Yes      | [SignInHookFailModeValue](/reference/schemas/#signinhookfailmodevalue) | —           |
| `timeout_ms` | Yes      | integer (`minimum: 100`; `maximum: 5000`)                              | —           |
| `enabled`    | Yes      | boolean                                                                | —           |
| `created_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                             | —           |
| `updated_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                             | —           |

## SignInHookCreate

No description.

| Property     | Required | Type and constraints                                                   | Description |
| ------------ | -------- | ---------------------------------------------------------------------- | ----------- |
| `point`      | Yes      | [SignInHookPointValue](/reference/schemas/#signinhookpointvalue)       | —           |
| `url`        | Yes      | string (`minLength: 9`; `maxLength: 2048`; `pattern: "^https://"`)     | —           |
| `fail_mode`  | No       | [SignInHookFailModeValue](/reference/schemas/#signinhookfailmodevalue) | —           |
| `timeout_ms` | No       | integer (`minimum: 100`; `maximum: 5000`; `default: 2000`)             | —           |
| `enabled`    | No       | boolean (`default: true`)                                              | —           |

## SignInHookDelivery

No description.

| Property          | Required | Type and constraints                             | Description                                                                                                                                                 |
| ----------------- | -------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`          | Yes      | string (`enum: ["sign_in_hook_delivery"]`)       | —                                                                                                                                                           |
| `id`              | Yes      | string                                           | The sign-in ID (`pre_profile_issue`) or the event ID (`post_directory_event`); also the cursor.                                                             |
| `hook_id`         | Yes      | [SignInHookId](/reference/schemas/#signinhookid) | —                                                                                                                                                           |
| `kind`            | Yes      | string (`enum: ["sign_in","directory_event"]`)   | —                                                                                                                                                           |
| `sign_in_id`      | No       | string                                           | —                                                                                                                                                           |
| `organization_id` | No       | string                                           | —                                                                                                                                                           |
| `connection_id`   | No       | string                                           | —                                                                                                                                                           |
| `event_id`        | No       | string                                           | —                                                                                                                                                           |
| `outcome`         | Yes      | string                                           | Sign-in calls: allowed, denied, failed_open or failed_closed. Directory deliveries: pending, delivered or failed. Clients must tolerate values added later. |
| `status_code`     | Yes      | integer or null                                  | The HTTP status the hook answered; null when it never answered.                                                                                             |
| `duration_ms`     | Yes      | integer or null                                  | The call's latency; null for directory deliveries.                                                                                                          |
| `attempts`        | Yes      | integer                                          | —                                                                                                                                                           |
| `created_at`      | Yes      | [Timestamp](/reference/schemas/#timestamp)       | —                                                                                                                                                           |

## SignInHookDeliveryList

No description.

| Property      | Required | Type and constraints                                                  | Description |
| ------------- | -------- | --------------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["list"]`)                                             | —           |
| `data`        | Yes      | Array of [SignInHookDelivery](/reference/schemas/#signinhookdelivery) | —           |
| `has_more`    | Yes      | boolean                                                               | —           |
| `next_cursor` | Yes      | string or null                                                        | —           |

## SignInHookFailModeValue

`closed` (default) refuses the sign-in when the hook does not answer validly; `open` continues without claims.

string (`enum: ["closed","open"]`)

## SignInHookId

No description.

string (`pattern: "^hook_[0-9A-HJKMNP-TV-Z]{26}$"`)

## SignInHookList

No description.

| Property | Required | Type and constraints                                  | Description |
| -------- | -------- | ----------------------------------------------------- | ----------- |
| `data`   | Yes      | Array of [SignInHook](/reference/schemas/#signinhook) | —           |

## SignInHookPointValue

No description.

string (`enum: ["pre_profile_issue","post_directory_event"]`)

## SignInHookTestResult

No description.

| Property      | Required | Type and constraints                             | Description                                                                                                                                                 |
| ------------- | -------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`      | Yes      | string (`enum: ["sign_in_hook_test"]`)           | —                                                                                                                                                           |
| `hook_id`     | Yes      | [SignInHookId](/reference/schemas/#signinhookid) | —                                                                                                                                                           |
| `outcome`     | Yes      | string                                           | pre_profile_issue: allowed, denied, failed_open or failed_closed. post_directory_event: delivered or failed.                                                |
| `status_code` | Yes      | integer or null                                  | —                                                                                                                                                           |
| `duration_ms` | Yes      | integer                                          | —                                                                                                                                                           |
| `error`       | Yes      | string or null                                   | The catalog failure cause when the call failed (timeout, transport, status, bad_signature, invalid_response, too_large, call_id_mismatch); null on success. |

## SignInHookUpdate

No description.

| Property     | Required | Type and constraints                                                   | Description |
| ------------ | -------- | ---------------------------------------------------------------------- | ----------- |
| `url`        | No       | string (`minLength: 9`; `maxLength: 2048`; `pattern: "^https://"`)     | —           |
| `fail_mode`  | No       | [SignInHookFailModeValue](/reference/schemas/#signinhookfailmodevalue) | —           |
| `timeout_ms` | No       | integer (`minimum: 100`; `maximum: 5000`)                              | —           |
| `enabled`    | No       | boolean                                                                | —           |

## SignInHookWithSecret

No description.

[See the full composed schema](/spec/openapi-v1.yaml)

## SignInId

No description.

string (`pattern: "^sgn_[0-9A-HJKMNP-TV-Z]{26}$"`)

## SignInList

No description.

| Property      | Required | Type and constraints                          | Description |
| ------------- | -------- | --------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                      | —           |
| `data`        | Yes      | Array of [SignIn](/reference/schemas/#signin) | —           |
| `has_more`    | Yes      | boolean                                       | —           |
| `next_cursor` | Yes      | string or null                                | —           |

## SignInRisk

The sign-in's risk assessment, present when the environment has a risk policy (Business+). Computed from the sign-in itself and short-lived counters; it never carries an address.

| Property   | Required | Type and constraints                                                        | Description                                                            |
| ---------- | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `score`    | Yes      | integer (`minimum: 0`; `maximum: 100`)                                      | —                                                                      |
| `reasons`  | Yes      | Array of [SignInRiskReasonValue](/reference/schemas/#signinriskreasonvalue) | —                                                                      |
| `degraded` | No       | boolean                                                                     | True when the counters could not be read, so some signals are missing. |

## SignInRiskActionValue

No description.

string (`enum: ["allow","step_up","deny"]`)

## SignInRiskPolicy

No description.

| Property     | Required | Type and constraints                                                        | Description |
| ------------ | -------- | --------------------------------------------------------------------------- | ----------- |
| `object`     | Yes      | object (`const: "sign_in_risk_policy"`)                                     | —           |
| `min_score`  | Yes      | integer (`minimum: 1`; `maximum: 100`)                                      | —           |
| `action`     | Yes      | [SignInRiskActionValue](/reference/schemas/#signinriskactionvalue)          | —           |
| `reasons`    | Yes      | Array of [SignInRiskReasonValue](/reference/schemas/#signinriskreasonvalue) | —           |
| `updated_at` | Yes      | [Timestamp](/reference/schemas/#timestamp)                                  | —           |

## SignInRiskPolicyInput

No description.

| Property    | Required | Type and constraints                                                        | Description |
| ----------- | -------- | --------------------------------------------------------------------------- | ----------- |
| `min_score` | Yes      | integer (`minimum: 1`; `maximum: 100`)                                      | —           |
| `action`    | Yes      | [SignInRiskActionValue](/reference/schemas/#signinriskactionvalue)          | —           |
| `reasons`   | No       | Array of [SignInRiskReasonValue](/reference/schemas/#signinriskreasonvalue) | —           |

## SignInRiskReasonValue

No description.

string (`enum: ["impossible_travel","brute_force","new_country","unrecognized_device"]`)

## SignInRiskSummary

No description.

| Property  | Required | Type and constraints                   | Description |
| --------- | -------- | -------------------------------------- | ----------- |
| `score`   | Yes      | integer (`minimum: 0`; `maximum: 100`) | —           |
| `reasons` | Yes      | Array of string                        | —           |

## SignInTimeline

No description.

| Property        | Required | Type and constraints                             | Description                                                                                                                                                                                                                       |
| --------------- | -------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_policy` | No       | string or null (`enum: ["member","guest",null]`) | How the organization admitted the sign-in (D183): `member` for an email on one of its verified domains, `guest` under its `guest_sso` policy. Null for a refused sign-in, a test sign-in and sign-ins recorded before 2026-11-07. |
| `doctor`        | No       | [DoctorOutput](/reference/schemas/#doctoroutput) | Deterministic diagnosis from recorded failure/check evidence; absent when no known diagnosis exists.                                                                                                                              |
| `sign_in_id`    | Yes      | [SignInId](/reference/schemas/#signinid)         | —                                                                                                                                                                                                                                 |
| `steps`         | Yes      | Array of object                                  | —                                                                                                                                                                                                                                 |

## SigninRPIDScope

How a custom sign-in host becomes the passkey relying party ID. `hostname` (default) uses the hostname itself; `registrable_domain` uses its registrable domain (eTLD+1).

string (`enum: ["hostname","registrable_domain"]`)

## SingleLogoutSettings

No description.

| Property                | Required | Type and constraints                             | Description                                                                                                                                                       |
| ----------------------- | -------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`                | Yes      | string (`const: "single_logout"`)                | —                                                                                                                                                                 |
| `connection_id`         | Yes      | [ConnectionId](/reference/schemas/#connectionid) | —                                                                                                                                                                 |
| `enabled`               | Yes      | boolean                                          | —                                                                                                                                                                 |
| `idp_slo_url`           | No       | string or null (`format: "uri"`)                 | —                                                                                                                                                                 |
| `idp_slo_response_url`  | No       | string or null (`format: "uri"`)                 | —                                                                                                                                                                 |
| `sp_slo_urls`           | No       | Array of string (`format: "uri"`)                | Our SingleLogoutService locations (primary, then standby host, then each verified custom broker host the connection receives sign-ins on) to register at the IdP. |
| `idp_slo_binding`       | No       | string or null (`enum: ["redirect","post"]`)     | The binding we send the IdP on; `post` for IdPs whose SingleLogoutService takes HTTP-POST only.                                                                   |
| `metadata_slo`          | No       | object or null                                   | The IdP SingleLogoutService read from its metadata (refresh or upload). Manual `idp_slo_url` overrides it.                                                        |
| `effective_idp_slo_url` | No       | string or null (`format: "uri"`)                 | The IdP SLO URL in use (manual, else metadata); null when none is known.                                                                                          |

## SingleLogoutSettingsUpdate

No description.

| Property               | Required | Type and constraints                                | Description |
| ---------------------- | -------- | --------------------------------------------------- | ----------- |
| `enabled`              | Yes      | boolean                                             | —           |
| `idp_slo_url`          | No       | string or null (`format: "uri"`; `maxLength: 2048`) | —           |
| `idp_slo_response_url` | No       | string or null (`format: "uri"`; `maxLength: 2048`) | —           |
| `idp_slo_binding`      | No       | string or null (`enum: ["redirect","post"]`)        | —           |

## SocialProvider

No description.

| Property      | Required | Type and constraints                                         | Description                                                                                                                                                                                                                                                                          |
| ------------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `object`      | Yes      | string (`const: "social_provider"`)                          | —                                                                                                                                                                                                                                                                                    |
| `provider`    | Yes      | [SocialProviderName](/reference/schemas/#socialprovidername) | —                                                                                                                                                                                                                                                                                    |
| `client_id`   | Yes      | string                                                       | The environment's own client ID; empty when the provider runs on OhAuthCat's demo app.                                                                                                                                                                                               |
| `enabled`     | Yes      | boolean                                                      | —                                                                                                                                                                                                                                                                                    |
| `credentials` | No       | string (`enum: ["own","demo","none"]`)                       | Which client signs users in. `own` is the environment's client; `demo` is OhAuthCat's demo app (sandbox environments without a client of their own only; add your own before going live); `none` means the provider cannot sign in (no client and no demo app for this environment). |
| `updated_at`  | Yes      | string (`format: "date-time"`)                               | —                                                                                                                                                                                                                                                                                    |

## SocialProviderList

No description.

| Property | Required | Type and constraints                                          | Description |
| -------- | -------- | ------------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                      | —           |
| `data`   | Yes      | Array of [SocialProvider](/reference/schemas/#socialprovider) | —           |

## SocialProviderName

Google and GitHub are on every plan; the others need Pro or above. For Apple, client_secret is the client-secret JWT you generate from your Sign in with Apple key.

string (`enum: ["google","microsoft","github","apple","gitlab","linkedin","slack"]`)

## SocialProviderUpdate

Send client_id and client_secret together. A sandbox environment may leave both out to sign users in with OhAuthCat's demo app for the provider (`user_social_demo_unavailable` when none is configured); a production environment always needs its own client.

| Property        | Required | Type and constraints                       | Description |
| --------------- | -------- | ------------------------------------------ | ----------- |
| `client_id`     | No       | string (`minLength: 1`; `maxLength: 512`)  | —           |
| `client_secret` | No       | string (`minLength: 1`; `maxLength: 4096`) | —           |
| `enabled`       | Yes      | boolean                                    | —           |

## SsfStream

No description.

| Property                   | Required | Type and constraints                             | Description                                                          |
| -------------------------- | -------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| `id`                       | Yes      | string (`pattern: "^ssft_[0-9a-f]{32}$"`)        | —                                                                    |
| `object`                   | Yes      | string (`const: "ssf_stream"`)                   | —                                                                    |
| `audience`                 | Yes      | string                                           | The `aud` of every SET on this stream.                               |
| `delivery_method`          | Yes      | string (`enum: ["push","poll"]`)                 | —                                                                    |
| `delivery_url`             | Yes      | string                                           | The push endpoint, or the signals role's poll URL for a poll stream. |
| `has_authorization_header` | No       | boolean                                          | A push stream sends a stored Authorization header (never shown).     |
| `events_requested`         | Yes      | Array of string                                  | —                                                                    |
| `events_delivered`         | Yes      | Array of string                                  | —                                                                    |
| `description`              | No       | string                                           | —                                                                    |
| `status`                   | Yes      | string (`enum: ["enabled","paused","disabled"]`) | —                                                                    |
| `created_at`               | Yes      | [Timestamp](/reference/schemas/#timestamp)       | —                                                                    |
| `updated_at`               | Yes      | [Timestamp](/reference/schemas/#timestamp)       | —                                                                    |

## SsfStreamCreate

No description.

| Property               | Required | Type and constraints                             | Description                                              |
| ---------------------- | -------- | ------------------------------------------------ | -------------------------------------------------------- |
| `delivery_method`      | No       | string (`enum: ["push","poll"]`)                 | Defaults to poll.                                        |
| `endpoint_url`         | No       | string (`maxLength: 2048`)                       | Push streams only; an https URL.                         |
| `authorization_header` | No       | string (`maxLength: 4096`)                       | Push streams only; sealed at rest and never shown again. |
| `events_requested`     | No       | Array of string                                  | —                                                        |
| `description`          | No       | string (`maxLength: 256`)                        | —                                                        |
| `status`               | No       | string (`enum: ["enabled","paused","disabled"]`) | —                                                        |

## SsfStreamList

No description.

| Property | Required | Type and constraints                                | Description |
| -------- | -------- | --------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                            | —           |
| `data`   | Yes      | Array of [SsfStream](/reference/schemas/#ssfstream) | —           |

## SsfStreamUpdate

No description.

[SsfStreamCreate](/reference/schemas/#ssfstreamcreate)

## SsfStreamVerify

No description.

| Property | Required | Type and constraints      | Description |
| -------- | -------- | ------------------------- | ----------- |
| `state`  | No       | string (`maxLength: 256`) | —           |

## SsoForwardedRequest

Lever D. Send exactly one of `saml_response` and `oidc_code`. The response is validated exactly like one posted to our own ACS or OIDC callback; `Destination` must equal a registered `forwarding.acs_urls` entry of the connection. `client_id` (a publishable key of the same environment) is required; it becomes the access token's audience.

| Property         | Required | Type and constraints                             | Description                                                                                                                    |
| ---------------- | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `connection`     | Yes      | [ConnectionId](/reference/schemas/#connectionid) | —                                                                                                                              |
| `saml_response`  | No       | string                                           | Base64 SAMLResponse as received by the app's own ACS.                                                                          |
| `relay_state`    | No       | string                                           | —                                                                                                                              |
| `acs_url`        | No       | string (`format: "uri"`)                         | The app's ACS URL the response was posted to; optional when the connection registers exactly one.                              |
| `in_response_to` | No       | string                                           | The ID of the AuthnRequest the app sent; omit only for an IdP-initiated response (refused unless the connection allows those). |
| `oidc_code`      | No       | string                                           | —                                                                                                                              |
| `redirect_uri`   | No       | string (`format: "uri"`)                         | —                                                                                                                              |
| `code_verifier`  | No       | string                                           | The PKCE verifier of the app's own OIDC authorization request (required with `oidc_code`).                                     |
| `nonce`          | No       | string                                           | The nonce of the app's own OIDC authorization request (required with `oidc_code`).                                             |
| `client_id`      | No       | string                                           | A publishable key (`pk_…`) of the same environment; the access token's audience. Required.                                     |

## SsoLogout

No description.

| Property     | Required | Type and constraints           | Description |
| ------------ | -------- | ------------------------------ | ----------- |
| `object`     | Yes      | string (`const: "sso_logout"`) | —           |
| `logout_url` | Yes      | string (`format: "uri"`)       | —           |
| `sign_in_id` | Yes      | string                         | —           |

## SsoLogoutStart

No description.

| Property     | Required | Type and constraints                        | Description                                                              |
| ------------ | -------- | ------------------------------------------- | ------------------------------------------------------------------------ |
| `profile_id` | Yes      | [ProfileId](/reference/schemas/#profileid)  | —                                                                        |
| `return_to`  | Yes      | string (`format: "uri"`; `maxLength: 2048`) | A registered redirect URI the browser returns to after the IdP logs out. |

## SsoToken

No description.

| Property       | Required | Type and constraints                   | Description                                                                        |
| -------------- | -------- | -------------------------------------- | ---------------------------------------------------------------------------------- |
| `access_token` | Yes      | string                                 | JWT (ADR-010), aud = client_id, 10 minutes; verify against /.well-known/jwks.json. |
| `token_type`   | Yes      | string (`const: "Bearer"`)             | —                                                                                  |
| `expires_in`   | Yes      | integer (`const: 600`)                 | —                                                                                  |
| `profile`      | Yes      | [Profile](/reference/schemas/#profile) | —                                                                                  |

## SsoTokenRequest

RFC 6749 §4.1.3 authorization-code grant with PKCE (RFC 7636, S256 only).

| Property        | Required | Type and constraints                       | Description                                                                 |
| --------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| `grant_type`    | Yes      | string (`enum: ["authorization_code"]`)    | —                                                                           |
| `code`          | Yes      | string (`minLength: 1`)                    | —                                                                           |
| `code_verifier` | Yes      | string (`minLength: 43`; `maxLength: 128`) | —                                                                           |
| `client_id`     | Yes      | string (`minLength: 1`)                    | The publishable key (pk_...) the code was requested with on /sso/authorize. |
| `redirect_uri`  | Yes      | string (`format: "uri"`)                   | —                                                                           |

## StandbyACSSelection

SAML only: how an AuthnRequest started on the standby host names the standby ACS. `url` (default) sends `AssertionConsumerServiceURL` (IdPs that match the URL exactly, such as Entra ID); `index` sends `AssertionConsumerServiceIndex="1"`, the standby ACS's index in our SP metadata (IdPs that match indexed "other requestable SSO URLs", such as Okta). Requests on the primary host always send the URL. Either way the response's `Destination` must equal the URL it arrives on.

string (`enum: ["url","index"]`)

## SubprocessorNoticeRemoval

No description.

| Property | Required | Type and constraints                                                        | Description                                    |
| -------- | -------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
| `token`  | Yes      | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`) | The token of the unsubscribe link (base64url). |

## SubprocessorNoticeSubscribe

No description.

| Property          | Required | Type and constraints                                                              | Description                                     |
| ----------------- | -------- | --------------------------------------------------------------------------------- | ----------------------------------------------- |
| `email`           | Yes      | string (`format: "email"`; `minLength: 1`; `maxLength: 254`)                      | Trimmed and lower-cased before it is stored.    |
| `turnstile_token` | Yes      | string (`minLength: 1`; `maxLength: 2048`)                                        | —                                               |
| `source`          | No       | string (`minLength: 1`; `maxLength: 32`; `pattern: "^[a-z0-9][a-z0-9_-]{0,31}$"`) | Optional attribution slug, for example landing. |

## TestEmail

No description.

| Property | Required | Type and constraints           | Description |
| -------- | -------- | ------------------------------ | ----------- |
| `object` | Yes      | string (`const: "test_email"`) | —           |
| `kind`   | Yes      | string                         | —           |
| `status` | Yes      | string (`enum: ["sent"]`)      | —           |

## TestEmailCreate

No description.

| Property | Required | Type and constraints                                                                            | Description                                               |
| -------- | -------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `kind`   | Yes      | string (`enum: ["cert_expiry","connection_error","domain_record_missing","scim_auth_failure"]`) | —                                                         |
| `to`     | Yes      | string (`maxLength: 320`)                                                                       | An owner's or admin's email of the environment's account. |

## Timestamp

RFC 3339, UTC.

string (`format: "date-time"`)

## TraceRequestId

The `Request-Id` response header of the call, which is its W3C trace ID (32 lowercase hex digits). Quote it in support requests.

string (`pattern: "^[0-9a-f]{32}$"`)

## TrustedIssuer

No description.

| Property          | Required | Type and constraints                                                       | Description |
| ----------------- | -------- | -------------------------------------------------------------------------- | ----------- |
| `object`          | Yes      | string (`const: "trusted_issuer"`)                                         | —           |
| `id`              | Yes      | string                                                                     | —           |
| `issuer`          | Yes      | string                                                                     | —           |
| `jwks_url`        | Yes      | string (`format: "uri"`)                                                   | —           |
| `audiences`       | Yes      | Array of string                                                            | —           |
| `algorithms`      | Yes      | Array of string                                                            | —           |
| `skew_seconds`    | Yes      | integer                                                                    | —           |
| `claim_mapping`   | No       | [TrustedIssuerClaimMapping](/reference/schemas/#trustedissuerclaimmapping) | —           |
| `organization_id` | No       | string or null                                                             | —           |
| `jit_by_domain`   | Yes      | boolean                                                                    | —           |
| `created_at`      | Yes      | string (`format: "date-time"`)                                             | —           |

## TrustedIssuerClaimMapping

No description.

| Property         | Required | Type and constraints      | Description |
| ---------------- | -------- | ------------------------- | ----------- |
| `subject`        | No       | string (`maxLength: 128`) | —           |
| `email`          | No       | string (`maxLength: 128`) | —           |
| `email_verified` | No       | string (`maxLength: 128`) | —           |
| `first_name`     | No       | string (`maxLength: 128`) | —           |
| `last_name`      | No       | string (`maxLength: 128`) | —           |

## TrustedIssuerCreate

No description.

| Property          | Required | Type and constraints                                                       | Description |
| ----------------- | -------- | -------------------------------------------------------------------------- | ----------- |
| `issuer`          | Yes      | string (`minLength: 1`; `maxLength: 1024`)                                 | —           |
| `jwks_url`        | Yes      | string (`format: "uri"`; `maxLength: 2048`)                                | —           |
| `audiences`       | Yes      | Array of string (`minLength: 1`; `maxLength: 1024`)                        | —           |
| `algorithms`      | Yes      | Array of string (`enum: ["RS256","ES256","EdDSA"]`)                        | —           |
| `skew_seconds`    | No       | integer (`minimum: 0`; `maximum: 300`; `default: 60`)                      | —           |
| `claim_mapping`   | No       | [TrustedIssuerClaimMapping](/reference/schemas/#trustedissuerclaimmapping) | —           |
| `organization_id` | No       | [OrganizationId](/reference/schemas/#organizationid)                       | —           |
| `jit_by_domain`   | No       | boolean (`default: false`)                                                 | —           |

## TrustedIssuerList

No description.

| Property | Required | Type and constraints                                        | Description |
| -------- | -------- | ----------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`const: "list"`)                                    | —           |
| `data`   | Yes      | Array of [TrustedIssuer](/reference/schemas/#trustedissuer) | —           |

## TrustedTokenExchange

No description.

| Property             | Required | Type and constraints                                                                                  | Description                                                                      |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `grant_type`         | Yes      | string (`const: "urn:ietf:params:oauth:grant-type:token-exchange"`)                                   | —                                                                                |
| `subject_token`      | Yes      | string (`minLength: 1`; `maxLength: 16384`)                                                           | —                                                                                |
| `subject_token_type` | Yes      | string (`enum: ["urn:ietf:params:oauth:token-type:jwt","urn:ietf:params:oauth:token-type:id_token"]`) | —                                                                                |
| `client_id`          | No       | string (`maxLength: 256`)                                                                             | The environment's publishable key the issued access token is for (its audience). |

## TrustedTokenProfile

No description.

| Property            | Required | Type and constraints                                              | Description                                    |
| ------------------- | -------- | ----------------------------------------------------------------- | ---------------------------------------------- |
| `object`            | Yes      | string (`const: "trusted_token_profile"`)                         | —                                              |
| `id`                | Yes      | string                                                            | Stable profile ID for this issuer and subject. |
| `issuer_id`         | Yes      | string                                                            | —                                              |
| `subject`           | Yes      | string                                                            | —                                              |
| `email`             | No       | string or null                                                    | —                                              |
| `email_verified`    | No       | boolean                                                           | —                                              |
| `first_name`        | No       | string or null                                                    | —                                              |
| `last_name`         | No       | string or null                                                    | —                                              |
| `organization_id`   | No       | string or null                                                    | —                                              |
| `expires_at`        | No       | string (`format: "date-time"`)                                    | —                                              |
| `access_token`      | No       | string                                                            | Present with client_id.                        |
| `issued_token_type` | No       | string (`const: "urn:ietf:params:oauth:token-type:access_token"`) | —                                              |
| `token_type`        | No       | string (`const: "Bearer"`)                                        | —                                              |
| `expires_in`        | No       | integer                                                           | —                                              |

## Upload

No description.

| Property         | Required | Type and constraints                                                        | Description                                                                                                                                      |
| ---------------- | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`             | Yes      | [UploadId](/reference/schemas/#uploadid)                                    | —                                                                                                                                                |
| `object`         | Yes      | string (`const: "upload"`)                                                  | —                                                                                                                                                |
| `upload_url`     | Yes      | string (`format: "uri"`)                                                    | Short-lived upload URL. Use the returned method and every required header value. Uploading alone does not create an import.                      |
| `upload_method`  | No       | string (`const: "PUT"`)                                                     | HTTP method returned by the object-store signer.                                                                                                 |
| `upload_headers` | No       | object (`additionalProperties: {"type":"array","items":{"type":"string"}}`) | Required signed request headers, preserving all values supplied by the object-store signer. No additional signed Content-Type guarantee is made. |
| `expires_at`     | Yes      | [Timestamp](/reference/schemas/#timestamp)                                  | —                                                                                                                                                |

## UploadCreate

No description.

| Property     | Required | Type and constraints                                                        | Description                                                                                                                                                                                            |
| ------------ | -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `purpose`    | Yes      | string (`enum: ["import_bundle","csv_saml","auth0_users","auth0_mapping"]`) | —                                                                                                                                                                                                      |
| `size_bytes` | Yes      | integer (`minimum: 1`)                                                      | Exact uploaded byte length. ImportBundle and CSV ZIP uploads are limited to 16 MiB. Auth0 JSON lines exports are limited to 64 MiB and streamed; Auth0 organization CSV mappings are limited to 5 MiB. |

## UploadId

No description.

string (`pattern: "^upl_[0-9A-HJKMNP-TV-Z]{26}$"`)

## UserAuthMethod

No description.

string (`enum: ["password","magic_code","passkey","social","sso"]`)

## UserManagementSettings

How the environment's end users sign in. Absent settings read as the defaults.

| Property                           | Required | Type and constraints                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------------- | -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_name`                         | No       | string or null (`maxLength: 100`)                             | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `methods`                          | Yes      | Array of [UserAuthMethod](/reference/schemas/#userauthmethod) | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `password_min_length`              | Yes      | integer (`minimum: 8`; `maximum: 64`)                         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `password_history`                 | Yes      | integer (`minimum: 0`; `maximum: 24`)                         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `password_check_breached`          | Yes      | boolean                                                       | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `password_require_character_types` | No       | boolean (`default: true`)                                     | Passwords must contain at least one uppercase letter, one lowercase letter, one number and one symbol (any character that is not a letter or digit; Unicode-aware, and a letter of a script without case counts as both upper and lower case). On by default for every environment (D191). A password that lacks one is refused with `password_invalid`, `param: password` and one `details` item per missing type (`problem`: `missing_uppercase`, `missing_lowercase`, `missing_number` or `missing_symbol`). Omitted on update means true. |
| `bind_browser`                     | Yes      | boolean                                                       | Email codes and reset links work only in the browser that asked for them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `mfa_policy`                       | Yes      | string (`enum: ["off","optional","required"]`)                | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `linking_rule`                     | Yes      | string (`enum: ["verified_email","never"]`)                   | Whether a social sign-in may join an existing user, and only on an email the provider asserts is verified.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `session_absolute_seconds`         | Yes      | integer (`minimum: 300`; `maximum: 7776000`)                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `session_idle_seconds`             | Yes      | integer (`minimum: 300`; `maximum: 7776000`)                  | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `require_name`                     | No       | boolean                                                       | Sign-up on the hosted pages asks for a first and last name. Absent reads as false.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `native_app_origins`               | No       | Array of string (`minLength: 8`; `maxLength: 200`)            | Native apps whose passkey ceremonies are accepted on the hosted sign-in relying party, as android:apk-key-hash:&lt;base64url SHA-256 of the signing certificate&gt; or ios:&lt;team id&gt;.&lt;bundle id&gt;. Absent reads as none.                                                                                                                                                                                                                                                                                                           |
| `android_apps`                     | No       | Array of [AndroidAppLink](/reference/schemas/#androidapplink) | Android package names for the sign-in host's /.well-known/assetlinks.json (passkeys and sign-in credentials shared with the app). Each apk_key_hash must also be listed in native_app_origins as android:apk-key-hash:&lt;hash&gt;. Absent reads as none.                                                                                                                                                                                                                                                                                     |

## UserManagementUsage

No description.

| Property       | Required | Type and constraints                      | Description                                                                                       |
| -------------- | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `object`       | Yes      | string (`const: "user_management_usage"`) | —                                                                                                 |
| `month`        | Yes      | string                                    | —                                                                                                 |
| `active_users` | Yes      | integer (`format: "int64"`)               | Distinct users who signed in during the month (a HyperLogLog estimate, about 1 % standard error). |
| `limit`        | Yes      | integer or null (`format: "int64"`)       | The plan's monthly active users; null when the plan has no fixed limit.                           |
| `plan`         | Yes      | string                                    | —                                                                                                 |

## VaultContext

Additional authenticated data bound to the ciphertext; the same pairs are needed to decrypt.

object (`additionalProperties: {"type":"string","maxLength":256}`)

## VaultDecryptRequest

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `ciphertext`   | Yes      | string (`maxLength: 98304`)                          | —           |
| `context`      | No       | [VaultContext](/reference/schemas/#vaultcontext)     | —           |

## VaultDecryptResult

No description.

| Property    | Required | Type and constraints                 | Description |
| ----------- | -------- | ------------------------------------ | ----------- |
| `object`    | Yes      | string (`enum: ["vault_plaintext"]`) | —           |
| `plaintext` | Yes      | string (`format: "byte"`)            | —           |

## VaultEncryptRequest

No description.

| Property       | Required | Type and constraints                                 | Description                                        |
| -------------- | -------- | ---------------------------------------------------- | -------------------------------------------------- |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                  |
| `key`          | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,63}$"`)    | The key name.                                      |
| `plaintext`    | Yes      | string (`format: "byte"`; `maxLength: 87384`)        | Base64 (standard, padded); at most 64 KiB decoded. |
| `context`      | No       | [VaultContext](/reference/schemas/#vaultcontext)     | —                                                  |

## VaultEncryptResult

No description.

| Property      | Required | Type and constraints                         | Description |
| ------------- | -------- | -------------------------------------------- | ----------- |
| `object`      | Yes      | string (`enum: ["vault_ciphertext"]`)        | —           |
| `ciphertext`  | Yes      | string                                       | —           |
| `key_id`      | Yes      | [VaultKeyId](/reference/schemas/#vaultkeyid) | —           |
| `key_version` | Yes      | integer                                      | —           |

## VaultKey

No description.

| Property          | Required | Type and constraints                                 | Description                                                                                                                                                                    |
| ----------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | Yes      | [VaultKeyId](/reference/schemas/#vaultkeyid)         | —                                                                                                                                                                              |
| `object`          | Yes      | string (`enum: ["vault_key"]`)                       | —                                                                                                                                                                              |
| `organization`    | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                                                                                                                                                              |
| `name`            | Yes      | string                                               | —                                                                                                                                                                              |
| `current_version` | Yes      | integer (`minimum: 1`)                               | —                                                                                                                                                                              |
| `created_at`      | Yes      | string (`format: "date-time"`)                       | —                                                                                                                                                                              |
| `rotated_at`      | Yes      | string (`format: "date-time"`)                       | —                                                                                                                                                                              |
| `usage`           | No       | [VaultKeyUsage](/reference/schemas/#vaultkeyusage)   | Successful encrypt and decrypt calls with this key over the last 30 UTC days (object writes and reads included), and when it was last used; returned by the list. Counts only. |

## VaultKeyCreate

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `name`         | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,63}$"`)    | —           |

## VaultKeyId

No description.

string (`pattern: "^vkey_[0-9A-HJKMNP-TV-Z]{26}$"`)

## VaultKeyList

No description.

| Property | Required | Type and constraints                              | Description |
| -------- | -------- | ------------------------------------------------- | ----------- |
| `object` | Yes      | string (`enum: ["list"]`)                         | —           |
| `data`   | Yes      | Array of [VaultKey](/reference/schemas/#vaultkey) | —           |

## VaultKeyUsage

No description.

| Property       | Required | Type and constraints                   | Description |
| -------------- | -------- | -------------------------------------- | ----------- |
| `encrypts`     | Yes      | integer (`format: "int64"`)            | —           |
| `decrypts`     | Yes      | integer (`format: "int64"`)            | —           |
| `last_used_at` | Yes      | string or null (`format: "date-time"`) | —           |

## VaultObject

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `object`       | Yes      | string (`enum: ["vault_object"]`)                    | —           |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `name`         | Yes      | string                                               | —           |
| `version`      | Yes      | integer (`minimum: 1`)                               | —           |
| `key_id`       | Yes      | [VaultKeyId](/reference/schemas/#vaultkeyid)         | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                       | —           |

## VaultObjectList

No description.

| Property | Required | Type and constraints                                    | Description |
| -------- | -------- | ------------------------------------------------------- | ----------- |
| `object` | Yes      | string (`enum: ["list"]`)                               | —           |
| `data`   | Yes      | Array of [VaultObject](/reference/schemas/#vaultobject) | —           |

## VaultObjectPut

No description.

| Property       | Required | Type and constraints                                 | Description                          |
| -------------- | -------- | ---------------------------------------------------- | ------------------------------------ |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —                                    |
| `key`          | Yes      | string (`pattern: "^[a-z0-9][a-z0-9_.-]{0,63}$"`)    | The Vault key name to encrypt under. |
| `value`        | Yes      | string (`format: "byte"`; `maxLength: 87384`)        | —                                    |

## VaultObjectValue

No description.

| Property       | Required | Type and constraints                                 | Description |
| -------------- | -------- | ---------------------------------------------------- | ----------- |
| `object`       | Yes      | string (`enum: ["vault_object"]`)                    | —           |
| `organization` | Yes      | [OrganizationId](/reference/schemas/#organizationid) | —           |
| `name`         | Yes      | string                                               | —           |
| `version`      | Yes      | integer                                              | —           |
| `key_id`       | Yes      | [VaultKeyId](/reference/schemas/#vaultkeyid)         | —           |
| `created_at`   | Yes      | string (`format: "date-time"`)                       | —           |
| `value`        | Yes      | string (`format: "byte"`)                            | —           |

## WaitlistJoin

No description.

| Property          | Required | Type and constraints                                                              | Description                                     |
| ----------------- | -------- | --------------------------------------------------------------------------------- | ----------------------------------------------- |
| `email`           | Yes      | string (`minLength: 1`; `maxLength: 254`)                                         | Trimmed and lower-cased before it is stored.    |
| `turnstile_token` | Yes      | string (`minLength: 1`; `maxLength: 2048`)                                        | —                                               |
| `source`          | No       | string (`minLength: 1`; `maxLength: 32`; `pattern: "^[a-z0-9][a-z0-9_-]{0,31}$"`) | Optional attribution slug, for example landing. |

## WaitlistRemoval

No description.

| Property | Required | Type and constraints                                                        | Description                                |
| -------- | -------- | --------------------------------------------------------------------------- | ------------------------------------------ |
| `token`  | Yes      | string (`minLength: 43`; `maxLength: 43`; `pattern: "^[A-Za-z0-9_-]{43}$"`) | The token of the removal link (base64url). |

## WebAuthnOptions

No description.

| Property     | Required | Type and constraints                  | Description |
| ------------ | -------- | ------------------------------------- | ----------- |
| `public_key` | Yes      | object (`additionalProperties: true`) | —           |

## WebhookDelivery

No description.

| Property          | Required | Type and constraints                                                 | Description                                                                                                                                                                                           |
| ----------------- | -------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`          | No       | string (`enum: ["native","workos"]`; `default: "native"`)            | Delivery format. Existing deliveries retain their captured format after endpoint changes.                                                                                                             |
| `id`              | Yes      | [WebhookDeliveryId](/reference/schemas/#webhookdeliveryid)           | —                                                                                                                                                                                                     |
| `object`          | Yes      | string (`const: "webhook_delivery"`)                                 | —                                                                                                                                                                                                     |
| `endpoint_id`     | Yes      | [WebhookEndpointId](/reference/schemas/#webhookendpointid)           | —                                                                                                                                                                                                     |
| `event_id`        | Yes      | [EventId](/reference/schemas/#eventid)                               | —                                                                                                                                                                                                     |
| `status`          | Yes      | string (`enum: ["pending","succeeded","failed"]`)                    | —                                                                                                                                                                                                     |
| `attempts`        | No       | integer                                                              | —                                                                                                                                                                                                     |
| `response_status` | No       | integer or null                                                      | —                                                                                                                                                                                                     |
| `event_type`      | No       | string                                                               | The type of the delivered event (e.g. `connection.activated`).                                                                                                                                        |
| `duration_ms`     | No       | integer or null (`minimum: 0`)                                       | How long the latest attempt took, in milliseconds. Null before the first attempt.                                                                                                                     |
| `next_attempt_at` | No       | string or null (`format: "date-time"`)                               | When a pending delivery is attempted next. Null once it succeeded or failed for good, and for a pending delivery that is not scheduled.                                                               |
| `request`         | No       | [WebhookDeliveryRequest](/reference/schemas/#webhookdeliveryrequest) | —                                                                                                                                                                                                     |
| `error`           | No       | string or null                                                       | Why the latest attempt failed, for example `timed out`, `connection failed`, a refused or unresolvable address, or `endpoint answered 500`. Null before the first attempt and after a successful one. |
| `response`        | No       | [See the full composed schema](/spec/openapi-v1.yaml)                | The response to the latest attempt. Null when there was no attempt yet or the attempt got no HTTP response (for example a timeout).                                                                   |
| `created_at`      | No       | [Timestamp](/reference/schemas/#timestamp)                           | —                                                                                                                                                                                                     |

## WebhookDeliveryId

No description.

string (`pattern: "^whdl_[0-9A-HJKMNP-TV-Z]{26}$"`)

## WebhookDeliveryList

No description.

| Property      | Required | Type and constraints                                            | Description |
| ------------- | -------- | --------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                        | —           |
| `data`        | Yes      | Array of [WebhookDelivery](/reference/schemas/#webhookdelivery) | —           |
| `has_more`    | Yes      | boolean                                                         | —           |
| `next_cursor` | Yes      | string or null                                                  | —           |

## WebhookDeliveryRequest

The request every attempt of the delivery sends. The signature header is always shown as `[redacted]` (each attempt is signed with a fresh timestamp and no signature is stored).

| Property         | Required | Type and constraints                               | Description                                     |
| ---------------- | -------- | -------------------------------------------------- | ----------------------------------------------- |
| `method`         | Yes      | string (`enum: ["POST"]`)                          | —                                               |
| `url`            | No       | string (`format: "uri"`)                           | The endpoint's current URL.                     |
| `headers`        | Yes      | object (`additionalProperties: {"type":"string"}`) | —                                               |
| `body`           | Yes      | string                                             | The event payload, cut to its first 4096 bytes. |
| `body_truncated` | Yes      | boolean                                            | —                                               |

## WebhookDeliveryResponse

The response the endpoint returned. Headers whose names suggest a credential (authorization, cookies, keys, secrets, sessions, signatures, tokens) are shown as `[redacted]`; at most 32 headers are kept, each value cut to 256 bytes. Responses recorded before headers were captured have an empty `headers`.

| Property  | Required | Type and constraints                               | Description                                                                    |
| --------- | -------- | -------------------------------------------------- | ------------------------------------------------------------------------------ |
| `status`  | Yes      | integer                                            | —                                                                              |
| `headers` | Yes      | object (`additionalProperties: {"type":"string"}`) | —                                                                              |
| `body`    | Yes      | string                                             | The start of the response body (at most 512 bytes), empty when there was none. |

## WebhookEndpoint

No description.

| Property     | Required | Type and constraints                                       | Description                                                                               |
| ------------ | -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `format`     | No       | string (`enum: ["native","workos"]`; `default: "native"`)  | Delivery format. Existing deliveries retain their captured format after endpoint changes. |
| `id`         | Yes      | [WebhookEndpointId](/reference/schemas/#webhookendpointid) | —                                                                                         |
| `object`     | Yes      | string (`const: "webhook_endpoint"`)                       | —                                                                                         |
| `url`        | Yes      | string (`format: "uri"`)                                   | —                                                                                         |
| `events`     | Yes      | Array of string                                            | —                                                                                         |
| `version`    | Yes      | string                                                     | —                                                                                         |
| `enabled`    | Yes      | boolean                                                    | —                                                                                         |
| `created_at` | No       | [Timestamp](/reference/schemas/#timestamp)                 | —                                                                                         |

## WebhookEndpointCreate

No description.

| Property  | Required | Type and constraints                                      | Description                                                                               |
| --------- | -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `format`  | No       | string (`enum: ["native","workos"]`; `default: "native"`) | Delivery format. Existing deliveries retain their captured format after endpoint changes. |
| `url`     | Yes      | string (`format: "uri"`)                                  | —                                                                                         |
| `events`  | Yes      | Array of string                                           | —                                                                                         |
| `version` | No       | string                                                    | —                                                                                         |
| `enabled` | No       | boolean                                                   | —                                                                                         |

## WebhookEndpointId

No description.

string (`pattern: "^whep_[0-9A-HJKMNP-TV-Z]{26}$"`)

## WebhookEndpointList

No description.

| Property      | Required | Type and constraints                                            | Description |
| ------------- | -------- | --------------------------------------------------------------- | ----------- |
| `object`      | Yes      | string (`const: "list"`)                                        | —           |
| `data`        | Yes      | Array of [WebhookEndpoint](/reference/schemas/#webhookendpoint) | —           |
| `has_more`    | Yes      | boolean                                                         | —           |
| `next_cursor` | Yes      | string or null                                                  | —           |

## WebhookEndpointUpdate

No description.

| Property  | Required | Type and constraints                                      | Description                                                                               |
| --------- | -------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `format`  | No       | string (`enum: ["native","workos"]`; `default: "native"`) | Delivery format. Existing deliveries retain their captured format after endpoint changes. |
| `url`     | No       | string (`format: "uri"`)                                  | —                                                                                         |
| `events`  | No       | Array of string                                           | —                                                                                         |
| `version` | No       | string                                                    | —                                                                                         |
| `enabled` | No       | boolean                                                   | —                                                                                         |

## WebhookSecret

No description.

| Property                     | Required | Type and constraints                                   | Description                           |
| ---------------------------- | -------- | ------------------------------------------------------ | ------------------------------------- |
| `endpoint`                   | Yes      | [WebhookEndpoint](/reference/schemas/#webhookendpoint) | —                                     |
| `secret`                     | Yes      | string                                                 | Shown once.                           |
| `previous_secret_expires_at` | No       | string or null (`format: "date-time"`)                 | Dual signing for 24 h after rotation. |

## WebhookTestRequest

No description.

| Property | Required | Type and constraints    | Description |
| -------- | -------- | ----------------------- | ----------- |
| `type`   | Yes      | string (`minLength: 1`) | —           |

## WorkOSDirectory

No description.

| Property          | Required | Type and constraints                                | Description |
| ----------------- | -------- | --------------------------------------------------- | ----------- |
| `id`              | Yes      | string                                              | —           |
| `object`          | Yes      | string (`const: "directory"`)                       | —           |
| `organization_id` | No       | string                                              | —           |
| `type`            | No       | string                                              | —           |
| `state`           | No       | string (`enum: ["validating","linked","unlinked"]`) | —           |
| `name`            | No       | string                                              | —           |
| `created_at`      | No       | string (`format: "date-time"`)                      | —           |
| `updated_at`      | No       | string (`format: "date-time"`)                      | —           |

## WorkOSDirectoryEmail

No description.

| Property | Required | Type and constraints | Description |
| -------- | -------- | -------------------- | ----------- |
| `value`  | Yes      | string               | —           |

## WorkOSDirectoryGroup

No description.

| Property          | Required | Type and constraints                | Description |
| ----------------- | -------- | ----------------------------------- | ----------- |
| `id`              | Yes      | string                              | —           |
| `object`          | Yes      | string (`const: "directory_group"`) | —           |
| `organization_id` | No       | string                              | —           |
| `directory_id`    | No       | string                              | —           |
| `idp_id`          | No       | string                              | —           |
| `name`            | No       | string                              | —           |
| `created_at`      | No       | string (`format: "date-time"`)      | —           |
| `updated_at`      | No       | string (`format: "date-time"`)      | —           |

## WorkOSDirectoryGroupList

No description.

| Property        | Required | Type and constraints                                                      | Description |
| --------------- | -------- | ------------------------------------------------------------------------- | ----------- |
| `object`        | Yes      | string (`const: "list"`)                                                  | —           |
| `data`          | Yes      | Array of [WorkOSDirectoryGroup](/reference/schemas/#workosdirectorygroup) | —           |
| `list_metadata` | Yes      | [WorkOSListMetadata](/reference/schemas/#workoslistmetadata)              | —           |

## WorkOSDirectoryList

No description.

| Property        | Required | Type and constraints                                            | Description |
| --------------- | -------- | --------------------------------------------------------------- | ----------- |
| `object`        | Yes      | string (`const: "list"`)                                        | —           |
| `data`          | Yes      | Array of [WorkOSDirectory](/reference/schemas/#workosdirectory) | —           |
| `list_metadata` | Yes      | [WorkOSListMetadata](/reference/schemas/#workoslistmetadata)    | —           |

## WorkOSDirectoryUser

No description.

| Property            | Required | Type and constraints                                                      | Description                                                                                                                    |
| ------------------- | -------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id`                | Yes      | string                                                                    | —                                                                                                                              |
| `object`            | Yes      | string (`const: "directory_user"`)                                        | —                                                                                                                              |
| `organization_id`   | No       | string                                                                    | —                                                                                                                              |
| `directory_id`      | No       | string                                                                    | —                                                                                                                              |
| `idp_id`            | No       | string                                                                    | —                                                                                                                              |
| `email`             | No       | string                                                                    | Primary mapped email when present.                                                                                             |
| `state`             | No       | string (`enum: ["active","inactive"]`)                                    | —                                                                                                                              |
| `first_name`        | No       | string                                                                    | —                                                                                                                              |
| `last_name`         | No       | string                                                                    | —                                                                                                                              |
| `emails`            | No       | Array of [WorkOSDirectoryEmail](/reference/schemas/#workosdirectoryemail) | —                                                                                                                              |
| `groups`            | No       | Array of [WorkOSDirectoryGroup](/reference/schemas/#workosdirectorygroup) | Deprecated WorkOS field; empty for new compatibility integrations. Query directory groups with the user filter for membership. |
| `role`              | No       | [WorkosRole](/reference/schemas/#workosrole)                              | —                                                                                                                              |
| `custom_attributes` | No       | [CustomAttributeValues](/reference/schemas/#customattributevalues)        | —                                                                                                                              |
| `created_at`        | No       | string (`format: "date-time"`)                                            | —                                                                                                                              |
| `updated_at`        | No       | string (`format: "date-time"`)                                            | —                                                                                                                              |

## WorkOSDirectoryUserList

No description.

| Property        | Required | Type and constraints                                                    | Description |
| --------------- | -------- | ----------------------------------------------------------------------- | ----------- |
| `object`        | Yes      | string (`const: "list"`)                                                | —           |
| `data`          | Yes      | Array of [WorkOSDirectoryUser](/reference/schemas/#workosdirectoryuser) | —           |
| `list_metadata` | Yes      | [WorkOSListMetadata](/reference/schemas/#workoslistmetadata)            | —           |

## WorkOSDsyncError

No description.

| Property  | Required | Type and constraints | Description |
| --------- | -------- | -------------------- | ----------- |
| `message` | Yes      | string               | —           |
| `code`    | No       | string               | —           |

## WorkOSListMetadata

No description.

| Property | Required | Type and constraints | Description |
| -------- | -------- | -------------------- | ----------- |
| `before` | Yes      | string or null       | —           |
| `after`  | Yes      | string or null       | —           |

## WorkosProfile

No description.

| Property            | Required | Type and constraints                                  | Description                                                               |
| ------------------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| `id`                | Yes      | string                                                | Imported WorkOS profile ID when present; otherwise the native profile ID. |
| `object`            | Yes      | string (`const: "profile"`)                           | —                                                                         |
| `connection_id`     | Yes      | string                                                | —                                                                         |
| `connection_type`   | Yes      | string (`enum: ["GenericSAML","GenericOIDC"]`)        | Generic protocol type; a vendor subtype is never inferred.                |
| `organization_id`   | Yes      | string                                                | —                                                                         |
| `idp_id`            | Yes      | string                                                | —                                                                         |
| `email`             | Yes      | string                                                | —                                                                         |
| `first_name`        | Yes      | string or null                                        | —                                                                         |
| `last_name`         | Yes      | string or null                                        | —                                                                         |
| `name`              | Yes      | string or null                                        | —                                                                         |
| `role`              | Yes      | [See the full composed schema](/spec/openapi-v1.yaml) | —                                                                         |
| `roles`             | Yes      | Array of [WorkosRole](/reference/schemas/#workosrole) | —                                                                         |
| `groups`            | Yes      | Array of string                                       | —                                                                         |
| `custom_attributes` | Yes      | object (`additionalProperties: true`)                 | —                                                                         |
| `raw_attributes`    | Yes      | object (`additionalProperties: true`)                 | Empty object; upstream raw attribute data was discontinued in April 2026. |

## WorkosRole

No description.

| Property | Required | Type and constraints | Description |
| -------- | -------- | -------------------- | ----------- |
| `slug`   | Yes      | string               | —           |

## WorkosToken

No description.

| Property       | Required | Type and constraints                               | Description |
| -------------- | -------- | -------------------------------------------------- | ----------- |
| `access_token` | Yes      | string                                             | —           |
| `token_type`   | Yes      | string (`const: "Bearer"`)                         | —           |
| `expires_in`   | Yes      | integer (`minimum: 1`)                             | —           |
| `profile`      | Yes      | [WorkosProfile](/reference/schemas/#workosprofile) | —           |

## WorkosTokenRequest

No description.

| Property        | Required | Type and constraints                        | Description                                                                                    |
| --------------- | -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `grant_type`    | Yes      | string (`enum: ["authorization_code"]`)     | —                                                                                              |
| `client_id`     | Yes      | string (`minLength: 1`; `maxLength: 256`)   | A live OhAuthCat publishable key, replacing the original vendor client identifier.             |
| `client_secret` | Yes      | string (`minLength: 1`; `maxLength: 256`)   | OhAuthCat secret API key with sso:exchange in the same environment; never persisted or logged. |
| `code`          | Yes      | string (`minLength: 1`; `maxLength: 32768`) | —                                                                                              |
| `code_verifier` | No       | string (`maxLength: 128`)                   | Optional SDK field; it never overrides the internally enforced sealed PKCE verifier.           |

All schema details, including nested properties and composition constraints, are available in the [OpenAPI document](/spec/openapi-v1.yaml).
