# Update a connection

<div class="api-op" data-api-operation>
<div class="api-op__main">

<p class="api-endpoint"><span class="method method-patch">PATCH</span> <code>/v1/connections/&#123;conn&#125;</code></p>

<dl class="api-facts"><div><dt>Scope</dt><dd><code>connections:write</code></dd></div><div><dt>Auth</dt><dd>Secret key (<code>sk_…</code>)</dd></div><div><dt>Since</dt><dd>1.0</dd></div></dl>

## Path parameters

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">conn</code> <span class="api-field__type">string</span> <span class="api-field__required">Required</span></p>
</li>
</ul>

## Headers

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">OhAuthCat-Version</code> <span class="api-field__type">string</span></p>
Minor version; defaults to the environment's pin.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">Idempotency-Key</code> <span class="api-field__type">string</span></p>
Honoured for 24 h; a replay returns the original response.

<p class="api-field__chips">min length 1 · max length 255</p>
</li>
</ul>

## Request body

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">name</code> <span class="api-field__type">string</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">saml_metadata_url</code> <span class="api-field__type">string (uri)</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">saml_metadata_xml</code> <span class="api-field__type">string</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">oidc_client_id</code> <span class="api-field__type">string</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">oidc_client_secret</code> <span class="api-field__type">string</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">sp_entity_id</code> <span class="api-field__type">string</span></p>
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.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">standby_acs_selection</code> <span class="api-field__type">string</span></p>
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.

<p class="api-field__chips">one of <code>url</code>, <code>index</code></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">forwarding</code> <span class="api-field__type">ConnectionForwardingUpdate</span></p>
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.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">idp_initiated</code> <span class="api-field__type">ConnectionIDPInitiated</span></p>
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.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">routing_domains</code> <span class="api-field__type">array of string</span></p>
</li>
</ul>

## Responses

<ul class="api-responses">
<li class="api-response"><span class="api-status api-status--ok">200</span> <span>OK <span class="api-field__type">Connection</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">400</span> <span>Invalid request. Codes: <a href="/errors/parameter_invalid/">parameter_invalid</a>, <a href="/errors/parameter_missing/">parameter_missing</a>, <a href="/errors/version_unsupported/">version_unsupported</a> and resource-specific codes from the catalogue. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">401</span> <span>Codes: <a href="/errors/authentication_required/">authentication_required</a>, <a href="/errors/api_key_invalid/">api_key_invalid</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">403</span> <span>Codes: <a href="/errors/api_key_scope_missing/">api_key_scope_missing</a>, <a href="/errors/ip_not_allowed/">ip_not_allowed</a>, <a href="/errors/plan_limit_reached/">plan_limit_reached</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">404</span> <span>Code: <a href="/errors/resource_not_found/">resource_not_found</a> (also returned for other tenants' IDs); a path no endpoint serves answers <a href="/errors/route_not_found/">route_not_found</a>. 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. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">409</span> <span>Codes: <a href="/errors/idempotency_key_reused/">idempotency_key_reused</a> and resource-specific conflicts. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">429</span> <span>Code: <a href="/errors/rate_limited/">rate_limited</a>. Retry-After is set. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">503</span> <span>Code: <a href="/errors/service_unavailable/">service_unavailable</a>. Retry-After is set; writes are paused. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--neutral">default</span> <span>Any other error, including <a href="/errors/internal_error/">internal_error</a>. Every code is in the error catalogue. <span class="api-field__type">Error</span></span></li>
</ul>

Errors share one shape; see the [error code catalogue](/errors/).

</div>
<div class="api-op__code">

**curl**

```sh wrap
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"
  ]
}'
```

**Node**

```javascript wrap
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();
```

**Python**

```python wrap
import os
import 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()
```

```json title="Response 200" wrap
{
  "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"
}
```

</div>
</div>
