update_sso_connection

Update a single sign-on connection

act entity tenant-private since 2026-10-01

Changes a single sign-on connection: its name, its IdP metadata (idp_metadata_url, an https URL, or idp_metadata, the IdP's metadata XML), and whether people sign in through it (active). Activating needs the metadata saved. Clerk is updated to match shortly after. Inputs left out are left as they are.

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
idempotency: natural
emits: sso_connection.updated
MCP tool: update_sso_connection
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/update_sso_connection

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org.
connection_id	uuid	required	UUID The connection, as list_sso_connections names it.
name	text	optional	1 to 120 characters A new name.
idp_metadata_url	text	optional	9 to 2048 characters The IdP's metadata URL, https. Replaces any uploaded XML.
idp_metadata	text	optional	1 to 200000 characters The IdP's metadata XML, uploaded. Replaces any metadata URL.
active	boolean	optional	Whether people sign in through it.

Response

connection_id · string · Trade HQ's id for the connection.
org_id · string · The org it belongs to.
name · string · What the org's admins call it.
protocol · string · saml or oidc.
domain · string · The verified email domain it serves.
status · string · creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.
active · boolean · Whether people sign in through it.
acs_url · stringnull · The service provider's ACS URL, for the IdP admin; null until Clerk has answered.
sp_entity_id · stringnull · The service provider's entity id, for the IdP admin; null until Clerk has answered.
sp_metadata_url · stringnull · The service provider's metadata URL; null until Clerk has answered.
idp_metadata_url · stringnull · The IdP metadata URL saved, if a URL was.
has_idp_metadata · boolean · Whether IdP metadata is saved, as a URL or as uploaded XML.
required · boolean · Whether members at its domain must sign in through it.
bypass_until · stringnull · While the outage lever holds, when it ends; null otherwise.
jit · boolean · Whether a first sign-in through it makes the person a member.
default_role_template · stringnull · The role template a just-in-time member gets.
idp_mfa_trusted · boolean · Whether the IdP's MFA counts toward the org's MFA settings.
allow_manual_additions · boolean · Whether invites stay allowed for its domain while a directory manages it (TRA-486).
last_sign_in_at · stringnull · The last sign-in through it.
idp_certificate_expires_at · stringnull · When the IdP's signing certificate expires, once known.
created_at · string · When it was added.
caller_may_bypass · boolean · Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "connection_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "Trade HQ's id for the connection.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org it belongs to.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "What the org's admins call it.",
      "x-data-class": "operational"
    },
    "protocol": {
      "type": "string",
      "enum": [
        "saml",
        "oidc"
      ],
      "description": "saml or oidc.",
      "x-data-class": "operational"
    },
    "domain": {
      "type": "string",
      "description": "The verified email domain it serves.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "creating",
        "awaiting_metadata",
        "ready_to_test",
        "active",
        "deleting",
        "deleted"
      ],
      "description": "creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.",
      "x-data-class": "operational"
    },
    "active": {
      "type": "boolean",
      "description": "Whether people sign in through it.",
      "x-data-class": "operational"
    },
    "acs_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The service provider's ACS URL, for the IdP admin; null until Clerk has answered.",
      "x-data-class": "operational"
    },
    "sp_entity_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The service provider's entity id, for the IdP admin; null until Clerk has answered.",
      "x-data-class": "operational"
    },
    "sp_metadata_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The service provider's metadata URL; null until Clerk has answered.",
      "x-data-class": "operational"
    },
    "idp_metadata_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The IdP metadata URL saved, if a URL was.",
      "x-data-class": "operational"
    },
    "has_idp_metadata": {
      "type": "boolean",
      "description": "Whether IdP metadata is saved, as a URL or as uploaded XML.",
      "x-data-class": "operational"
    },
    "required": {
      "type": "boolean",
      "description": "Whether members at its domain must sign in through it.",
      "x-data-class": "operational"
    },
    "bypass_until": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "While the outage lever holds, when it ends; null otherwise.",
      "x-data-class": "operational"
    },
    "jit": {
      "type": "boolean",
      "description": "Whether a first sign-in through it makes the person a member.",
      "x-data-class": "operational"
    },
    "default_role_template": {
      "type": [
        "string",
        "null"
      ],
      "description": "The role template a just-in-time member gets.",
      "x-data-class": "operational"
    },
    "idp_mfa_trusted": {
      "type": "boolean",
      "description": "Whether the IdP's MFA counts toward the org's MFA settings.",
      "x-data-class": "operational"
    },
    "allow_manual_additions": {
      "type": "boolean",
      "description": "Whether invites stay allowed for its domain while a directory manages it (TRA-486).",
      "x-data-class": "operational"
    },
    "last_sign_in_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The last sign-in through it.",
      "x-data-class": "operational"
    },
    "idp_certificate_expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the IdP's signing certificate expires, once known.",
      "x-data-class": "operational"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was added.",
      "x-data-class": "operational"
    },
    "caller_may_bypass": {
      "type": "boolean",
      "description": "Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "connection_id",
    "org_id",
    "name",
    "protocol",
    "domain",
    "status",
    "active",
    "acs_url",
    "sp_entity_id",
    "sp_metadata_url",
    "idp_metadata_url",
    "has_idp_metadata",
    "required",
    "bypass_until",
    "jit",
    "default_role_template",
    "idp_mfa_trusted",
    "allow_manual_additions",
    "last_sign_in_at",
    "idp_certificate_expires_at",
    "created_at",
    "caller_may_bypass"
  ],
  "additionalProperties": false
}

Refusals

connection_not_found · 422 · the org has no such connection
metadata_required · 422 · a connection is activated only once its IdP metadata is saved
connection_not_created · 409 · Clerk has not created the connection yet; try again shortly
connection_required · 409 · SSO is required through this connection, so it cannot be deactivated
invalid_metadata · 422 · IdP metadata is an https URL or XML, one of the two
security_policy_unenforced · 422 · the stored sso section does not parse

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileD5

APIF

MCPF*

VoiceD2

PushF

OneBoxN

OutboundN

Mobile: degraded: composition
MCP: approval required
Voice: degraded: confirmation
OneBox: no document originates a sign-in connection
Outbound: crosses to no counterparty

Events

sso_connection.updated audit_only

create_access_review, create_sso_connection, delete_sso_connection, invite_user, set_sso_policy

get a test key

curl https://api.containertradehq.com/v1/cap/update_sso_connection \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_id>","connection_id":"00000000-0000-4000-8000-000000000000"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.updateSsoConnection({
  "org_id": "<org_id>",
  "connection_id": "00000000-0000-4000-8000-000000000000"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.update_sso_connection({
    "org_id": "<org_id>",
    "connection_id": "00000000-0000-4000-8000-000000000000",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_sso_connection",
    "arguments": {
      "org_id": "<org_id>",
      "connection_id": "00000000-0000-4000-8000-000000000000"
    }
  }
}

MCP

update_sso_connection · readOnlyHint false · approval required

“Call update_sso_connection”