Skip to content
Dashboard
Theme
Theme

API schemas

Request and response schemas of the v1 API, version 1.0.0.

View Markdown

API version 1.0.0.

No description.

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

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.

No description.

Property Required Type and constraints Description
id Yes 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 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 —
organization No OrganizationId Set on an organization-scoped key.

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") —

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.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ApiKey —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
api_key Yes ApiKey —
secret Yes string Shown once.
previous_key_expires_at No string or null (format: "date-time") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ApiKeyExtraSecret —

No description.

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

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.

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) —

No description.

Property Required Type and constraints Description
custom_attributes Yes CustomAttributeValues —
warnings Yes Array of CustomAttributeWarning —
source Yes 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."}) —

No description.

Property Required Type and constraints Description
id Yes 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["audit_log_event"]) —
id Yes AuditLogEventId —
organization_id Yes OrganizationId —
action Yes string —
version Yes integer —
occurred_at Yes Timestamp —
created_at Yes Timestamp —
actor Yes AuditLogParty —
targets Yes Array of AuditLogParty —
context Yes AuditLogContext —
metadata No AuditLogMetadata —

No description.

Property Required Type and constraints Description
organization_id Yes OrganizationId —
event Yes AuditLogEventInput —

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
action Yes string (maxLength: 128) —
occurred_at Yes Timestamp —
version No integer (minimum: 1; maximum: 10000) The schema version to validate against; the latest when absent.
actor Yes AuditLogParty —
targets Yes Array of AuditLogParty —
context No AuditLogContext —
metadata No AuditLogMetadata —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of AuditLogEvent —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes 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") —

No description.

Property Required Type and constraints Description
from Yes Timestamp —
to Yes Timestamp —
actor No string —
action No string —
target No string —
organization No OrganizationId Environment exports only (POST /v1/audit_logs/exports); the same organization filter as GET /v1/audit_logs. The account export rejects it.

No description.

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

No description.

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

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)

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of AuditLog —
has_more Yes boolean —
next_cursor Yes string or null —

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)

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 —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["audit_log_schema"]) —
action Yes string —
version Yes integer —
actor No AuditLogSchemaActor —
targets Yes Array of AuditLogSchemaTarget —
metadata No AuditLogJSONSchema —
created_at Yes Timestamp —

No description.

Property Required Type and constraints Description
metadata No AuditLogJSONSchema —

No description.

Property Required Type and constraints Description
action Yes string (maxLength: 128) Lowercase dotted words, e.g. user.signed_in.
actor No AuditLogSchemaActor —
targets Yes Array of AuditLogSchemaTarget —
metadata No AuditLogJSONSchema —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of AuditLogSchema —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

No description.

Property Required Type and constraints Description
checks Yes Array of AuthorizationCheck —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of AuthorizationDecision —

Name a membership, or a user and an organization.

Property Required Type and constraints Description
membership No MembershipId —
user No EndUserId —
organization No OrganizationId —
permission Yes PermissionSlug —
resource No AuthzResource —

No description.

Property Required Type and constraints Description
object Yes string (const: "authorization_decision") —
authorized Yes boolean —
membership No MembershipId —

No description.

Property Required Type and constraints Description
type Yes AuthzResourceType —
id Yes string (minLength: 1; maxLength: 256) —

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

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

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.

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of BotDetection —
has_more Yes boolean —
next_cursor Yes string or null —

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 —

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 —

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) —

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 —
dark No 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 —

No description.

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

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}$") —

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 —
card_background No BrandingColorPair —
text No BrandingColorPair —
muted_text No BrandingColorPair —
accent No BrandingColorPair —
border No BrandingColorPair —

No description.

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

No description.

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

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 —

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.

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

Property Required Type and constraints Description
light No BrandingTheme —
dark No 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 —

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 —
consent No BrandingSurface —
email No BrandingSurface —

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 —

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 —
dark No 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 ;{}<>"'\\()/*@: 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 —

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 —
not_after Yes Timestamp —
created_at No Timestamp —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Certificate —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
oidc_managed No ConnectionManagedOIDC —
catalogue_idp No PortalIDPId Explicit backend catalogue selection; never inferred from issuer URLs, protocol or imported metadata.
id Yes ConnectionId —
object Yes string (const: "connection") —
legacy_ids No 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 —
idp_initiated No ConnectionIDPInitiated —
organization_id No 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 —
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 —
updated_at No Timestamp —

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 —

No description.

Property Required Type and constraints Description
object Yes string (const: "connection_client_keys") —
connection_id Yes ConnectionId —
jwks_uri Yes string (format: "uri") —
keys Yes Array of ConnectionClientKey —

No description.

Property Required Type and constraints Description
organization Yes 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 —
oidc_managed No ConnectionManagedOIDC —
catalogue_idp No 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.

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.

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") —

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 —
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) —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ConnectionHealth —
has_more Yes boolean —
next_cursor Yes string or null —

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) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Connection —
has_more Yes boolean —
next_cursor Yes string or null —

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) —

No description.

Property Required Type and constraints Description
directory_id Yes DirectoryId —
match_key No string (enum: ["externalId","userName"]; default: "externalId") —

No description.

Property Required Type and constraints Description
id Yes ConnectionShareId —
object Yes string (const: "connection_share") —
connection_id Yes ConnectionId —
owner_organization_id Yes OrganizationId —
organization_id Yes OrganizationId —
routing_domains Yes Array of string —
created_at Yes string (format: "date-time") —
revoked_at No string (format: "date-time") —

No description.

Property Required Type and constraints Description
organization Yes 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.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ConnectionShare —

No description.

Property Required Type and constraints Description
test_url Yes string (format: "uri") —
expires_at No Timestamp —
attempt_id No SignInId This attempt; the test result’s attempt_id matches it once the test sign-in is recorded.
started_at No Timestamp —

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|us|µs|ms|s|m|h)([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|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).

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 —
forwarding No ConnectionForwardingUpdate —
idp_initiated No ConnectionIDPInitiated —
routing_domains No Array of string —

No description.

Property Required Type and constraints Description
mappings Yes Array of 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"]) —

No description.

See the full composed schema

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"})

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"]) —

No description.

Property Required Type and constraints Description
id Yes 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 —
created_at No Timestamp —

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 Email only. Exact DKIM TXT or CNAME configuration records.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of CustomDomain —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes DebugBundleId —
sign_in Yes SignInId —
connection Yes ConnectionId —
created_at Yes Timestamp —
expires_at Yes Timestamp —
diagnostic_available Yes boolean —

No description.

Property Required Type and constraints Description
sign_in Yes SignInId —

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 —
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 —
failing_invariant Yes string (maxLength: 256) —
idp_metadata Yes object (additionalProperties: false) —
saml_response No string (maxLength: 262144) —
assertion No string (maxLength: 262144) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of DebugBundleSummary —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
url Yes string (format: "uri") —
expires_at Yes Timestamp —

No description.

Property Required Type and constraints Description
bundle Yes DebugBundleId —
revoked Yes integer (minimum: 0) Live share links ended by this call.

No description.

Property Required Type and constraints Description
id Yes DebugBundleId —
sign_in Yes SignInId —
connection Yes ConnectionId —
created_at Yes Timestamp —
expires_at Yes Timestamp —

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 —
remaining Yes integer (minimum: 0; maximum: 20) —

No description.

Property Required Type and constraints Description

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "dev_event") —
id Yes EventId —
type Yes string —
created_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
object Yes string (const: "dev_init") —
environment Yes Environment —
redirect_uri No See the full composed schema —
redirect_uri_created Yes boolean —
relay_path Yes string The relay WebSocket path on the API host (/v1/dev/relay).
organization No Organization The test organization; present when test_connection was requested.
connection No 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") —

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.

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 —
object Yes string (const: "directory") —
legacy_ids No 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 —
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 —

No description.

Property Required Type and constraints Description
organization Yes 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.

No description.

Property Required Type and constraints Description
directory No 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.

No description.

Property Required Type and constraints Description
id Yes DirectoryGroupId —
object Yes string (const: "directory_group") —
legacy_ids No 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 —
idp_id No string —
name Yes string —
created_at No Timestamp —
updated_at No Timestamp —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of DirectoryGroup —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Directory —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
object Yes string (const: "directory_source") —
directory_id Yes DirectoryId —
kind Yes string (enum: ["bamboohr","rippling_hris","google_admin_sdk","sftp_csv","workday","hibob","personio","gusto"]) —
next_sync_at Yes Timestamp —
last_synced_at No 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 Up to 20 of the people the last successful poll did not sync, with the reason; absent when it skipped none.

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.

No description.

Property Required Type and constraints Description
object Yes string (const: "directory_source_oauth") —
directory_id Yes 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 —
updated_at Yes Timestamp —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "directory_source_oauth_start") —
directory_id Yes DirectoryId —
provider Yes string (enum: ["gusto","bamboohr","google"]) —
authorization_url Yes string (format: "uri") —
expires_at Yes Timestamp —

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.

No description.

Property Required Type and constraints Description
id Yes string The directory provider value.
name Yes string —
portal_idp No 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 —
availability No 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.

No description.

Property Required Type and constraints Description
object Yes string (const: "directory_source_ssh_key") —
directory_id Yes 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "directory_sync") —
directory_id Yes 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 Up to 20 of the people not synced, with the reason.

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.

No description.

Property Required Type and constraints Description
name No string “” clears the name.

No description.

Property Required Type and constraints Description
custom_attributes No CustomAttributeValues —
custom_attribute_warnings No Array of 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 —
object Yes string (const: "directory_user") —
legacy_ids No 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 —
organization_id No 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 —
updated_at No Timestamp —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of DirectoryUser —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

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 —

No description.

Property Required Type and constraints Description
id Yes DomainId —
object Yes string (const: "domain") —
organization_id No 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 —

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Domain —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
include_subdomains Yes boolean —

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") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EmailEvent —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes EncryptionKeyId —
object Yes string (enum: ["encryption_key"]) —
scope Yes string (enum: ["environment","organization"]) —
organization No 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") —

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 Register an organization key instead of the environment-wide key.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of EncryptionKey —
reseals Yes Array of EncryptionKeyReseal —

No description.

Property Required Type and constraints Description
scope Yes string (enum: ["environment","organization"]) —
organization No OrganizationId —
target_key Yes 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") —

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.

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

Property Required Type and constraints Description
id Yes 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 —
state Yes 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") —

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 —

No description.

Property Required Type and constraints Description
id Yes 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") —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EndUserFactor —

No description.

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

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") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EndUserIdentity —

No description.

Property Required Type and constraints Description
id Yes EndUserInviteId —
object Yes string (const: "invite") —
email Yes string —
organization Yes See the full composed schema —
role Yes See the full composed schema —
state Yes EndUserInviteState —
expires_at Yes string (format: "date-time") —
created_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
email Yes string (minLength: 3; maxLength: 320) —
organization No OrganizationId —
role No MembershipRole —
inviter No EndUserId —

No description.

See the full composed schema

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EndUserInvite —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EndUser —
has_more Yes boolean —
next_cursor Yes string or null —

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).

No description.

Property Required Type and constraints Description
object Yes string (const: "passkey_authentication") —
user Yes 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 —

No description.

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

No description.

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

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.

No description.

Property Required Type and constraints Description
id Yes EndUserSessionId —
object Yes string (const: "session") —
user Yes 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") —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of EndUserSession —

No description.

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

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 —
state No EndUserState —

No description.

Property Required Type and constraints Description
id Yes EnvironmentId —
object Yes string (const: "environment") —
project No 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 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 —

No description.

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

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 —
data_classes Yes Array of ResidencyPlacement —

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.<domain>.
rp_id Yes string The WebAuthn relying party ID new end-user passkeys bind to.
rp_id_scope Yes 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") —

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.<domain>.
rp_id_scope No SigninRPIDScope —
confirm Yes string (maxLength: 253) The new host typed by the user; must equal hostname (or signin.<domain> when hostname is null).

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.

No description.

Property Required Type and constraints Description
error Yes 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 —
details No Array of 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.

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.

No description.

Property Required Type and constraints Description
id Yes EventId —
object Yes string (const: "event") —
type Yes string —
created_at Yes Timestamp —
environment Yes EnvironmentId —
organization No OrganizationId —
directory No DirectoryId —
sequence No integer —
api_version Yes string —
data Yes object (additionalProperties: true) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Event —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes 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 —
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 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.

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 —

No description.

Property Required Type and constraints Description
organization No OrganizationId Export only this organization (default the whole environment).

No description.

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

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.

No description.

Property Required Type and constraints Description
object Yes string (enum: ["feature_flag"]) —
id Yes FeatureFlagId —
key Yes string —
name Yes string —
description No string —
kind Yes string (enum: ["boolean","multivariate"]) —
enabled Yes boolean —
variants Yes Array of FeatureFlagVariant —
off_variant Yes string —
rules Yes Array of FeatureFlagRule —
fallthrough Yes FeatureFlagServe —
revision Yes integer —
created_at Yes Timestamp —
updated_at Yes Timestamp —

No description.

Property Required Type and constraints Description
keys No Array of string (maxLength: 128) —
context No FeatureFlagContext —

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) —

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}) —

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 —
off_variant No string Defaults to false for a boolean flag and the first variant otherwise.
rules No Array of FeatureFlagRule —
fallthrough No FeatureFlagServe —

No description.

Property Required Type and constraints Description
key Yes string (maxLength: 128) —
context No FeatureFlagContext —

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.

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of FeatureFlagEvaluation —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of FeatureFlag —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
conditions Yes Array of FeatureFlagCondition —
serve Yes FeatureFlagServe —

Exactly one of variant and rollout.

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

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 —
off_variant No string —
rules No Array of FeatureFlagRule —
fallthrough No FeatureFlagServe —

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).

No description.

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

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 —
dns_verified Yes boolean —
region No string —
smtp_host No string —
smtp_port No integer —
templates Yes Array of ITEmailTemplate —
updated_at Yes Timestamp —

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 —
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 —

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.

No description.

Property Required Type and constraints Description
id Yes 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 —
updated_at No Timestamp —
completed_at No Timestamp —

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 —

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.

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) —

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 —
directories No Array of ImportBundleDirectory —

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 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 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 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ImportSummary —
has_more Yes boolean —
next_cursor Yes string or null —

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 —

No description.

Property Required Type and constraints Description
cleanup No boolean Also deactivate the organization’s active imported connections.

An import without its plan.

Property Required Type and constraints Description
id Yes 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 —
updated_at No Timestamp —
completed_at No Timestamp —

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"])

No description.

Property Required Type and constraints Description
id Yes 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 —

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ItContact —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
id Yes 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 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.

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) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of LogStream —

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

string (maxLength: 512)

No description.

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

No description.

Property Required Type and constraints Description
id Yes M2MClientId —
object Yes string (const: "m2m_client") —
organization No OrganizationId —
name Yes string (maxLength: 200) —
auth_method Yes 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 —
audiences Yes Array of 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") —

No description.

Property Required Type and constraints Description
name Yes string (minLength: 1; maxLength: 200) —
organization No OrganizationId —
auth_method No M2MAuthMethod —
jwks No object (additionalProperties: true) —
scopes No Array of M2MScope —
audiences Yes Array of M2MAudience —
access_token_seconds No integer (minimum: 60; maximum: 3600) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of M2MClient —
has_more Yes boolean —
next_cursor Yes string or null —

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 —
audiences No Array of M2MAudience —
access_token_seconds No integer (minimum: 60; maximum: 3600) —

No description.

Property Required Type and constraints Description
client Yes M2MClient —
client_secret No string Shown once. Store it in your secret manager.

No description.

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

No description.

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

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

object (additionalProperties: true)

No description.

Property Required Type and constraints Description
id Yes MembershipId —
object Yes string (const: "organization_membership") —
organization Yes OrganizationId —
user Yes EndUserId —
role Yes MembershipRole —
state Yes MembershipState —
created_at Yes string (format: "date-time") —
updated_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
user Yes EndUserId —
role No MembershipRole —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Membership —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
object Yes string (const: "membership_permissions") —
membership Yes MembershipId —
roles Yes Array of MembershipRole Highest priority first.
permissions Yes Array of PermissionSlug —
resource_permissions No Array of PermissionSlug Extra permissions on the requested resource.

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

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

No description.

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

No description.

Property Required Type and constraints Description
role No MembershipRole —
state No MembershipState —

No description.

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

No description.

Property Required Type and constraints Description
id Yes 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") —

No description.

Property Required Type and constraints Description
client Yes OAuthClient —
client_secret Yes string or null Shown once, for confidential clients.

No description.

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

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 —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of OAuthClient —
has_more Yes boolean —

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") —

No description.

Property Required Type and constraints Description
id Yes OAuthGrantId —
object Yes string (const: "oauth_grant") —
client Yes OAuthClientId —
client_name Yes string —
user Yes 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") —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of OAuthGrant —
has_more Yes boolean —

No description.

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

No description.

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

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 —

No description.

Property Required Type and constraints Description
id Yes 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") —

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) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of OAuthResource —

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) —

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") —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of OAuthScope —

No description.

Property Required Type and constraints Description
id Yes OrganizationId —
object Yes string (const: "organization") —
legacy_ids No 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 —
consent_screen No string (enum: ["environment_default","on","off"]) —
metadata No Metadata —
created_at Yes Timestamp —
updated_at No Timestamp —

No description.

Property Required Type and constraints Description
object Yes string (const: "organization_allowed_intents") —
organization_id Yes OrganizationId —
allowed_intents Yes Array of Intent —

No description.

Property Required Type and constraints Description
allowed_intents Yes Array of Intent —

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 —

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 —
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 —

No description.

Property Required Type and constraints Description
id Yes 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") —

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.

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Organization —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
object Yes string (const: "organization_oauth_settings") —
organization Yes OrganizationId —
third_party_apps Yes string (enum: ["allow","deny"]) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "organization_profile") —
organization_id Yes 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.

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 —

No description.

Property Required Type and constraints Description
organization_id Yes OrganizationId —
intents Yes Array of object —

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 —
consent_screen No string (enum: ["environment_default","on","off"]) —
metadata No Metadata —

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.

No description.

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

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 —
status Yes string (enum: ["linked","unlinked"]) —
linked_at Yes Timestamp —
unlinked_at Yes string or null (format: "date-time") —
grants Yes PassportGrants —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of PassportLink —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes PermissionId —
object Yes string (const: "permission") —
slug Yes 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") —

No description.

Property Required Type and constraints Description
slug Yes PermissionSlug —
name No string (maxLength: 200) —
description No string (maxLength: 1000) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Permission —
has_more Yes boolean —
next_cursor Yes string or null —

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

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

No description.

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

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 —
scopes Yes Array of string —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["pipe_connect_session"]) —
connection Yes PipeConnection —
connect_url Yes string (format: "uri") —
expires_at Yes Timestamp —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["pipe_connection"]) —
id Yes PipeConnectionId —
provider Yes string —
organization_id Yes 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 —
created_at Yes Timestamp —
updated_at Yes Timestamp —

No description.

Property Required Type and constraints Description
provider Yes string (maxLength: 64) —
organization_id Yes OrganizationId —
user_id Yes string (minLength: 1; maxLength: 256) —
return_url Yes string (maxLength: 2048) One of the environment’s registered redirect URIs.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of PipeConnection —
has_more Yes boolean —
next_cursor Yes string or null —

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 —
updated_at Yes Timestamp —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of PipeProvider —

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) —

No description.

Property Required Type and constraints Description
id Yes PolicyId —
object Yes string (const: "policy") —
organization No OrganizationId —
kind Yes PolicyKindValue —
config Yes PolicyConfig —
exclusions Yes Array of string —
created_at Yes string (format: "date-time") —
updated_at Yes string (format: "date-time") —

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 —
rules No Array of PolicyRule —

No description.

Property Required Type and constraints Description
organization No OrganizationId —
kind Yes PolicyKind —
config Yes PolicyConfig —
exclusions No Array of string —

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 —

No description.

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

No description.

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

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

string

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Policy —
has_more Yes boolean —

No description.

Property Required Type and constraints Description
action Yes string (enum: ["allow","deny"]) —
expr Yes PolicyExpression —

No description.

Property Required Type and constraints Description
config No PolicyConfig —
exclusions No Array of string —

No description.

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

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"])

No description.

Property Required Type and constraints Description
completion No PortalSetupCompletion —
profile No PortalProfileId —
id Yes PortalInviteId —
object Yes string (const: "portal_invite") —
organization_id No OrganizationId —
intents No Array of 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 —
created_at No Timestamp —

No description.

Property Required Type and constraints Description
profile No PortalProfileId —
organization Yes OrganizationId —
intents Yes Array of 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of PortalInvite —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes PortalLinkId —
object Yes string (const: "portal_link") —
url Yes string (format: "uri") Shown once.
expires_at Yes Timestamp —

No description.

Property Required Type and constraints Description
profile No PortalProfileId —
organization Yes OrganizationId —
intents Yes Array of Intent —
return_url No string (format: "uri") —
success_urls No object (additionalProperties: {"type":"string","format":"uri"}) —
connection No 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 —

No description.

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

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

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of PortalLinkInfo —
has_more Yes boolean —
next_cursor Yes string or null —

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

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 —
allowed_features Yes Array of PortalFeature —
required_attributes Yes Array of string (minLength: 1; maxLength: 64) —
id Yes PortalProfileId —
object Yes string (const: "portal_profile") —
created_at Yes Timestamp —
updated_at Yes Timestamp —

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 —
allowed_features Yes Array of PortalFeature —
required_attributes Yes Array of string (minLength: 1; maxLength: 64) —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of PortalProfile —
has_more Yes boolean (const: false) —

No description.

Property Required Type and constraints Description
features Yes Array of PortalFeature —
connection No ConnectionId —
directory No DirectoryId —
object Yes string (const: "portal_setup_completion") —
completed_at Yes Timestamp —

No description.

Property Required Type and constraints Description
attempt_id No 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 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 Connection Doctor output for a failed test (cause and IdP-specific fix steps); absent otherwise.

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 —
custom_attributes No CustomAttributeValues —
policy_hints No 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 —
object Yes string (const: "profile") —
organization_id Yes OrganizationId —
connection_id Yes 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.

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

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

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.

No description.

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

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 —

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"])

No description.

Property Required Type and constraints Description
object Yes string (const: "provider_catalogue") —
sso Yes Array of SSOProvider —
directories Yes Array of DirectorySourceProvider —

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

string

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 —
created_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
email Yes string (format: "email"; minLength: 3; maxLength: 254) —
idps No Array of RadarIdpType —

No description.

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

No description.

Property Required Type and constraints Description
id Yes RedirectUriId —
object Yes string (const: "redirect_uri") —
uri Yes string (format: "uri") —
created_at No Timestamp —

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.

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of RedirectUri —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

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

No description.

Property Required Type and constraints Description
id Yes 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 The API key of the call; absent for dashboard, CLI and portal sessions.
organization_id No 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 —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of RequestLog —
has_more Yes boolean —
next_cursor Yes string or null —

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 The home region; present only when scope is home_region.
personal_data Yes boolean —

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"])

No description.

Property Required Type and constraints Description
id Yes RoleId —
object Yes string (const: "role") —
organization No OrganizationId —
slug Yes 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 —
created_at Yes string (format: "date-time") —
updated_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
id Yes RoleAssignmentId —
object Yes string (const: "role_assignment") —
membership Yes MembershipId —
role Yes MembershipRole —
role_id No RoleId —
resource No AuthzResource —
source Yes string (enum: ["api","sso"]) —
created_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
role Yes MembershipRole —
resource No AuthzResource —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of RoleAssignment —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
slug Yes MembershipRole —
organization No OrganizationId —
name No string (maxLength: 200) —
description No string (maxLength: 1000) —
priority No integer (minimum: 0; maximum: 10000) —
permissions No Array of PermissionSlug —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of Role —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
id Yes RoleRuleId —
object Yes string (const: "role_rule") —
organization No OrganizationId —
kind Yes RoleRuleKind —
match Yes RoleRuleMatch —
role Yes string —
priority Yes integer (format: "int64") —
condition No PolicyRule —
created_at Yes string (format: "date-time") —
updated_at Yes string (format: "date-time") —

No description.

Property Required Type and constraints Description
action Yes string (enum: ["allow","deny"]) —
expr Yes PolicyExpression —

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 —
role Yes string (minLength: 1; maxLength: 128) —
priority Yes integer (format: "int64") —
condition No RoleRuleCondition —

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of RoleRule —
has_more Yes boolean —

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}$") —

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 —

No description.

Property Required Type and constraints Description
organization Yes OrganizationId —
connection Yes 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 —
draft No RoleRuleCreate —

No description.

Property Required Type and constraints Description
match No RoleRuleMatch —
role No string (minLength: 1; maxLength: 128) —
priority No integer (format: "int64") —
clear_condition No boolean —
condition No RoleRuleCondition —

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 Replaces the role’s permissions.

No description.

Property Required Type and constraints Description
object Yes string (const: "sp_key_rotation") —
connection Yes ConnectionId —
generation Yes SPKeyRotationGeneration —
state Yes string (enum: ["staged","activated","rolled_back","retired"]) —
current_key Yes SPKeyRotationPublicKey —
previous_key Yes SPKeyRotationPublicKey —
next_key Yes 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 —
test No SPKeyRotationTestProof —
acknowledged_at No string (format: "date-time") —
test_eligible_at No string (format: "date-time") —
submission No 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") —

No description.

Property Required Type and constraints Description
generation Yes SPKeyRotationGeneration —

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

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

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) —

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

object (additionalProperties: false)

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) —

No description.

Property Required Type and constraints Description
object Yes string (const: "sp_key_rotation_test") —
generation Yes SPKeyRotationGeneration —
test_url Yes string (format: "uri") —
expires_at Yes string (format: "date-time") —

No description.

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

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 —
protocols Yes Array of string (enum: ["saml","oidc"]) —
saml No SSOProviderSAML —
oidc No 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 —

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 —

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 —

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.

No description.

Property Required Type and constraints Description
environment Yes 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") —

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.

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.

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"]) —

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}$") —

No description.

Property Required Type and constraints Description
object Yes string (const: "scim_replay") —
directory Yes DirectoryId —
idp Yes string —
outcome Yes string (enum: ["passed","failed"]) —
steps Yes Array of 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") —

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.

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 —

No description.

Property Required Type and constraints Description
id Yes 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of ScimRequest —
has_more Yes boolean —
next_cursor Yes string or null —

No description.

Property Required Type and constraints Description
import Yes ImportId —
legacy_profile_id Yes string (minLength: 1) —

No description.

Property Required Type and constraints Description
profile Yes Profile —

No description.

Property Required Type and constraints Description
id Yes SignInId —
object Yes string (const: "sign_in") —
connection_id No 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 —
test No boolean True for a test sign-in (listed only with include_test=true); absent for a real one.
risk No 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.

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) —

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 —
object Yes object (const: "sign_in_hook") —
point Yes SignInHookPointValue —
url Yes string (format: "uri"; maxLength: 2048) —
fail_mode Yes SignInHookFailModeValue —
timeout_ms Yes integer (minimum: 100; maximum: 5000) —
enabled Yes boolean —
created_at Yes Timestamp —
updated_at Yes Timestamp —

No description.

Property Required Type and constraints Description
point Yes SignInHookPointValue —
url Yes string (minLength: 9; maxLength: 2048; pattern: "^https://") —
fail_mode No SignInHookFailModeValue —
timeout_ms No integer (minimum: 100; maximum: 5000; default: 2000) —
enabled No boolean (default: true) —

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 —
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 —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of SignInHookDelivery —
has_more Yes boolean —
next_cursor Yes string or null —

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

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

No description.

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

No description.

Property Required Type and constraints Description
data Yes Array of SignInHook —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["sign_in_hook_test"]) —
hook_id Yes 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.

No description.

Property Required Type and constraints Description
url No string (minLength: 9; maxLength: 2048; pattern: "^https://") —
fail_mode No SignInHookFailModeValue —
timeout_ms No integer (minimum: 100; maximum: 5000) —
enabled No boolean —

No description.

See the full composed schema

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of SignIn —
has_more Yes boolean —
next_cursor Yes string or null —

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 —
degraded No boolean True when the counters could not be read, so some signals are missing.

No description.

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

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 —
reasons Yes Array of SignInRiskReasonValue —
updated_at Yes Timestamp —

No description.

Property Required Type and constraints Description
min_score Yes integer (minimum: 1; maximum: 100) —
action Yes SignInRiskActionValue —
reasons No Array of SignInRiskReasonValue —

No description.

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

No description.

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

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 Deterministic diagnosis from recorded failure/check evidence; absent when no known diagnosis exists.
sign_in_id Yes SignInId —
steps Yes Array of object —

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"])

No description.

Property Required Type and constraints Description
object Yes string (const: "single_logout") —
connection_id Yes 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.

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"]) —

No description.

Property Required Type and constraints Description
object Yes string (const: "social_provider") —
provider Yes 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") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of SocialProvider —

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"])

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 —

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 —
updated_at Yes Timestamp —

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"]) —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of SsfStream —

No description.

SsfStreamCreate

No description.

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

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 —
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.

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 —

No description.

Property Required Type and constraints Description
profile_id Yes ProfileId —
return_to Yes string (format: "uri"; maxLength: 2048) A registered redirect URI the browser returns to after the IdP logs out.

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 —

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") —

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"])

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).

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.

No description.

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

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.

RFC 3339, UTC.

string (format: "date-time")

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}$")

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 —
organization_id No string or null —
jit_by_domain Yes boolean —
created_at Yes string (format: "date-time") —

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) —

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 —
organization_id No OrganizationId —
jit_by_domain No boolean (default: false) —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of TrustedIssuer —

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).

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 —

No description.

Property Required Type and constraints Description
id Yes 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 —

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.

No description.

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

No description.

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

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 —
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:<base64url SHA-256 of the signing certificate> or ios:<team id>.<bundle id>. Absent reads as none.
android_apps No Array of 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:<hash>. Absent reads as none.

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 —

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

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

No description.

Property Required Type and constraints Description
organization Yes OrganizationId —
ciphertext Yes string (maxLength: 98304) —
context No VaultContext —

No description.

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

No description.

Property Required Type and constraints Description
organization Yes 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 —

No description.

Property Required Type and constraints Description
object Yes string (enum: ["vault_ciphertext"]) —
ciphertext Yes string —
key_id Yes VaultKeyId —
key_version Yes integer —

No description.

Property Required Type and constraints Description
id Yes VaultKeyId —
object Yes string (enum: ["vault_key"]) —
organization Yes 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 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.

No description.

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

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of VaultKey —

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") —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (enum: ["list"]) —
data Yes Array of VaultObject —

No description.

Property Required Type and constraints Description
organization Yes 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) —

No description.

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

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.

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).

No description.

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

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 —
object Yes string (const: "webhook_delivery") —
endpoint_id Yes WebhookEndpointId —
event_id Yes 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 —
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 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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of WebhookDelivery —
has_more Yes boolean —
next_cursor Yes string or null —

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 —

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.

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 —
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 —

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 —

No description.

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

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of WebhookEndpoint —
has_more Yes boolean —
next_cursor Yes string or null —

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 —

No description.

Property Required Type and constraints Description
endpoint Yes WebhookEndpoint —
secret Yes string Shown once.
previous_secret_expires_at No string or null (format: "date-time") Dual signing for 24 h after rotation.

No description.

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

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") —

No description.

Property Required Type and constraints Description
value Yes string —

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") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of WorkOSDirectoryGroup —
list_metadata Yes WorkOSListMetadata —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of WorkOSDirectory —
list_metadata Yes WorkOSListMetadata —

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 —
groups No Array of WorkOSDirectoryGroup Deprecated WorkOS field; empty for new compatibility integrations. Query directory groups with the user filter for membership.
role No WorkosRole —
custom_attributes No CustomAttributeValues —
created_at No string (format: "date-time") —
updated_at No string (format: "date-time") —

No description.

Property Required Type and constraints Description
object Yes string (const: "list") —
data Yes Array of WorkOSDirectoryUser —
list_metadata Yes WorkOSListMetadata —

No description.

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

No description.

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

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 —
roles Yes Array of 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.

No description.

Property Required Type and constraints Description
slug Yes string —

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 —

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.