set_sso_policy

Set an org's single sign-on settings

act entity tenant-private since 2026-10-01

Sets the org's single sign-on settings for one connection and its domain: whether members at the domain must sign in through the connection (required), just-in-time membership on a first sign-in (jit) and the role template it gives (default_role_template, never the Owner), whether the IdP's MFA counts toward the org's MFA settings (idp_mfa_trusted), and allow_manual_additions. bypass "start" is the IdP-outage lever: for 24 hours members at the domain may use magic link and passkey again; only the account owner or an Owner may pull it, and "end" lifts it early. 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: security_policy.changed
MCP tool: set_sso_policy
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/set_sso_policy

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.
required	boolean	optional	Whether members at the connection's domain must sign in through it. Needs an active connection.
jit	boolean	optional	Whether a first sign-in through the connection makes the person a member.
default_role_template	text	optional	1 to 64 characters The role template a just-in-time member gets: a shipped template other than owner, or one of this org's own.
idp_mfa_trusted	boolean	optional	Whether the IdP's MFA counts toward this org's MFA settings.
allow_manual_additions	boolean	optional	Whether invites stay allowed for the domain while a directory manages it.
bypass	one_of	optional	one of start, end start: allow magic link and passkey at the domain for 24 hours (the IdP-outage lever; account owner or Owner only). end: stop that early.

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
connection_not_active · 422 · SSO cannot be required through a connection that is not active: nobody at the domain could sign in
jit_needs_template · 422 · just-in-time membership needs a default role template
owner_not_assignable · 422 · the Owner role template is never given by a sign-in
unknown_role_template · 422 · the role template is neither shipped nor one of this org's
permission_not_held · 422 · the role template carries a permission the caller's own role in this org does not
bypass_owner_only · 422 · only the account owner or a holder of the Owner role template may allow magic link and passkey during an IdP outage
sso_not_required · 422 · the domain does not require SSO, so there is nothing to bypass
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

MobileF

APIF

MCPF*

VoiceD2

PushF

OneBoxN

OutboundN

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

Events

security_policy.changed audit_only

delete_sso_connection, update_sso_connection

get a test key

curl https://api.containertradehq.com/v1/cap/set_sso_policy \
  -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.setSsoPolicy({
  "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.set_sso_policy({
    "org_id": "<org_id>",
    "connection_id": "00000000-0000-4000-8000-000000000000",
})

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

MCP

set_sso_policy · readOnlyHint false · approval required

“Call set_sso_policy”