Skip to content
Dashboard
Theme
Theme

Update a connection

PATCH /v1/connections/{conn}: Update a connection.

View Markdown

PATCH /v1/connections/{conn}

Scope
connections:write
Auth
Secret key (sk_…)
Since
1.0
  • conn string Required

  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • Idempotency-Key string

    Honoured for 24 h; a replay returns the original response.

    min length 1 · max length 255

  • name string

  • saml_metadata_url string (uri)

  • saml_metadata_xml string

  • oidc_client_id string

  • oidc_client_secret string

  • sp_entity_id 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 string

    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.

    one of url, index

  • forwarding ConnectionForwardingUpdate

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

  • idp_initiated ConnectionIDPInitiated

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

  • routing_domains array of string

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"
]
}'
Response 200
{
"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"
}