1. Docs
  2. API Reference
  3. Update an SSO connection

Update an SSO connection

PATCH/portal/v1/accounts/{accountSlug}/sso/connections/{id}

Updates a connection's SAML/OIDC config; only fields present in the body are changed, and passing oidc_client_secret re-encrypts it while passing null clears it and omitting it leaves the stored secret untouched. If the connection is currently active, required-field validation is re-run so an edit cannot leave a live connection unactivatable. Emits an sso.connection.updated audit row recording the changed field names; responds 404 when the connection is not found in the Account.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Requires capability sso.manageSecurity

Manage SSO connections, domains, and directory sync. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.

Path Parameters

idstring Required

Request body

application/json

namestring Optional

Human label, e.g. "Acme Corp Okta".

email_domainsstring[] Optional
saml_entity_idstring Optional
saml_sso_urlstring Optional
saml_slo_urlstring Optional
saml_signing_certstring Optional

IdP X.509 signing certificate (PEM).

saml_signature_algorithmstring Optional
saml_want_assertions_signedboolean Optional
saml_name_id_formatstring Optional
force_authnboolean Optional

Force the IdP to re-authenticate the user on every login (SAML ForceAuthn / OIDC max_age=0). Prevents silent reuse of a stale IdP session on shared devices.

oidc_discovery_urlstring Optional
oidc_client_idstring Optional
oidc_client_secretstring Optional

OIDC client secret (plaintext in; encrypted at rest).

oidc_scopesstring[] Optional
attribute_mappingobject Optional
jit_provisioning_enabledboolean Optional

Responses

application/json

  • dataSsoConnectionResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on.

403account.capability_requiredForbidden
When it happens

The signed-in user's administrator roles do not grant the capability this endpoint requires.

Remediation

Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.

Returned object

SsoConnectionResponseDtoView all properties on this resource
Request
curl -X PATCH "https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/sso/connections/value" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "email_domains": [
      "string"
    ],
    "saml_entity_id": "string",
    "saml_sso_url": "string",
    "saml_slo_url": "string",
    "saml_signing_cert": "string",
    "saml_signature_algorithm": "string",
    "saml_want_assertions_signed": false,
    "saml_name_id_format": "string",
    "force_authn": false,
    "oidc_discovery_url": "string",
    "oidc_client_id": "string",
    "oidc_client_secret": "string",
    "oidc_scopes": [
      "string"
    ],
    "attribute_mapping": {},
    "jit_provisioning_enabled": false
  }'
Response
{
  "data": {
    "id": "string",
    "account_id": "string",
    "scope": "admin",
    "type": "saml",
    "name": "string",
    "status": "configuring",
    "email_domains": [
      "string"
    ],
    "saml_entity_id": "string",
    "saml_sso_url": "string",
    "saml_slo_url": "string",
    "saml_signing_cert": "string",
    "saml_signature_algorithm": "string",
    "saml_want_assertions_signed": false,
    "saml_name_id_format": "string",
    "force_authn": false,
    "oidc_discovery_url": "string",
    "oidc_client_id": "string",
    "oidc_scopes": [
      "string"
    ],
    "has_oidc_client_secret": false,
    "jit_provisioning_enabled": false,
    "attribute_mapping": {},
    "last_login_at": "2026-04-20T12:00:00.000Z",
    "last_login_failure_at": "2026-04-20T12:00:00.000Z",
    "consecutive_failures": 0,
    "auto_disabled_at": "2026-04-20T12:00:00.000Z",
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z"
  }
}
 Related endpoints
GETList SSO connections
POSTCreate an SSO connection
GETGet an SSO connection
DELETEDelete an SSO connection
POSTActivate an SSO connection
POSTDisable an SSO connection
GETList OAuth-client links for an end-user connection
POSTLink an OAuth client to an end-user connection
PATCHUpdate an OAuth-client link
DELETEUnlink an OAuth client from a connection
GETList Environment bindings for an end-user connection
POSTBind an end-user connection to an Environment
PATCHUpdate an Environment binding
DELETEUnbind an end-user connection from an Environment
GETList the organizations an end-user connection is bound to
GETList a connection's recent login attempts
GETList an OAuth client's SSO connection links
GETList Environments reachable by SSO
GETList SSO domain claims
POSTClaim a domain for admin SSO
POSTVerify a claimed domain
DELETERemove a domain claim
 Was this page helpful?

Tell us how we can improve this guide.

Canopy