PATCH /v1/connections/{conn}
- Scope
connections:write- Auth
- Secret key (
sk_…) - Since
- 1.0
Path parameters
Section titled “Path parameters”connstring Required
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Honoured for 24 h; a replay returns the original response.Idempotency-Keystringmin length 1 · max length 255
Request body
Section titled “Request body”namestringsaml_metadata_urlstring (uri)saml_metadata_xmlstringoidc_client_idstringoidc_client_secretstring
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.sp_entity_idstring
SAML only: how an AuthnRequest started on the standby host names the standby ACS.standby_acs_selectionstringurl(default) sendsAssertionConsumerServiceURL(IdPs that match the URL exactly, such as Entra ID);indexsendsAssertionConsumerServiceIndex="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’sDestinationmust equal the URL it arrives on.one of
url,index
Lever D settings, replaced as a whole when sent.forwardingConnectionForwardingUpdateuntilmust 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 oneacs_urlsentry and OIDC connections oneredirect_urisentry while forwarding is on.
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.idp_initiatedConnectionIDPInitiatedrouting_domainsarray of string
Responses
Section titled “Responses”- 200 OK Connection
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 404 Code: resource_not_found (also returned for other tenants’ IDs); a path no endpoint serves answers route_not_found. A browser GET or HEAD of an unknown path whose Accept ranks text/html above JSON gets an HTML 404 page instead, with the same status; every other client gets this JSON body. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
Errors share one shape; see the error code catalogue.
curl -X PATCH \ "https://api.ohauthcat.com/v1/connections/conn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5" \ -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "saml_metadata_url": "https://app.acme.com/callback", "saml_metadata_xml": "example_saml_metadata_xml", "oidc_client_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "oidc_client_secret": "sk_test_example", "sp_entity_id": "https://idp.acme.com/saml/metadata", "standby_acs_selection": "url", "forwarding": { "acs_urls": [ "https://app.acme.com/callback" ], "redirect_uris": [ "https://app.acme.com/callback" ], "until": "2026-01-15T09:30:00Z" }, "idp_initiated": { "enabled": false, "client_id": "client_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "default_redirect_uri": "https://app.acme.com/callback" }, "routing_domains": [ "acme.com" ]}'const response = await fetch("https://api.ohauthcat.com/v1/connections/conn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Acme Corp", "saml_metadata_url": "https://app.acme.com/callback", "saml_metadata_xml": "example_saml_metadata_xml", "oidc_client_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "oidc_client_secret": "sk_test_example", "sp_entity_id": "https://idp.acme.com/saml/metadata", "standby_acs_selection": "url", "forwarding": { "acs_urls": [ "https://app.acme.com/callback" ], "redirect_uris": [ "https://app.acme.com/callback" ], "until": "2026-01-15T09:30:00Z" }, "idp_initiated": { "enabled": false, "client_id": "client_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "default_redirect_uri": "https://app.acme.com/callback" }, "routing_domains": [ "acme.com" ] }),});const data = await response.json();import osimport requests
response = requests.patch( "https://api.ohauthcat.com/v1/connections/conn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "name": "Acme Corp", "saml_metadata_url": "https://app.acme.com/callback", "saml_metadata_xml": "example_saml_metadata_xml", "oidc_client_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "oidc_client_secret": "sk_test_example", "sp_entity_id": "https://idp.acme.com/saml/metadata", "standby_acs_selection": "url", "forwarding": { "acs_urls": [ "https://app.acme.com/callback", ], "redirect_uris": [ "https://app.acme.com/callback", ], "until": "2026-01-15T09:30:00Z", }, "idp_initiated": { "enabled": False, "client_id": "client_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "default_redirect_uri": "https://app.acme.com/callback", }, "routing_domains": [ "acme.com", ], },)data = response.json(){ "oidc_managed": { "provider": "google_workspace", "entra_tenant_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "allow_personal_accounts": false }, "catalogue_idp": "okta", "id": "conn_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "object": "connection", "legacy_ids": { "workos": "org_01H8ZQ4M7K2X8V3N5B6C1D0E9F" }, "forwarding": { "acs_urls": [ "https://app.acme.com/callback" ], "redirect_uris": [ "https://app.acme.com/callback" ], "until": "2026-01-15T09:30:00Z", "expires_in_days": 0, "last_warning_days": 1, "hint": "example_hint" }, "idp_initiated": { "enabled": false, "client_id": "client_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "default_redirect_uri": "https://app.acme.com/callback" }, "organization_id": "org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "name": "Acme Corp", "type": "saml", "state": "draft", "sp_entity_id": "https://idp.acme.com/saml/metadata", "sp_metadata_url": "https://app.acme.com/callback", "test_idp": true, "acs_urls": [ "https://app.acme.com/callback" ], "sp_slo_urls": [ "https://app.acme.com/callback" ], "routing_domains": [ "acme.com" ], "standby_registered": true, "import_source": "example_import_source", "import_lever": "A", "standby_acs_selection": "url", "idp_entity_id": "https://idp.acme.com/saml/metadata", "oidc_issuer": "https://idp.acme.com/saml/metadata", "metadata_stale_since": "2026-01-15T09:30:00Z", "untested_since": "2026-01-15T09:30:00Z", "created_at": "2026-01-15T09:30:00Z", "updated_at": "2026-01-15T09:30:00Z"}