1. Docs
  2. API Reference
  3. List SSO connections

List SSO connections

GET/portal/v1/accounts/{accountSlug}/sso/connections

Lists the SSO connections owned by the current Account, scoped to ctx.accountId. Accepts an optional scope query parameter (admin or end_user) to filter by connection scope; any other value is ignored and all connections are returned. Each entry covers SAML or OIDC config with secrets redacted, and the response is an unpaginated { items } array.

Authentication

Bearer TokenAuthorization

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

Requires capability sso.viewSecurity

View 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

accountSlugstring Required

The Account's slug. An unknown one answers 404.

Query Parameters

scopestring Optional

Responses

application/json

  • itemsSsoConnectionResponseDto[]*

application/json

  • errorApiErrorBodyDto*

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, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs.

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 GET "https://auth.canopy-io.com/portal/v1/accounts/value/sso/connections?scope=value" \
  -H "Authorization: Bearer $CANOPY_TOKEN"
Response
{
  "items": [
    {
      "id": "string",
      "account_id": "string",
      "scope": "admin",
      "type": "saml",
      "name": "string",
      "status": "configuring",
      "owner_organization_node_id": "string",
      "owned_by_organization": false,
      "saml_metadata_url": "string",
      "last_test_sign_in": {
        "test_id": "string",
        "outcome": "success",
        "reason": "string",
        "email": "string",
        "domain_outcome": "accepted",
        "completed_at": "2026-04-20T12:00:00.000Z"
      },
      "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",
      "created_at": "2026-04-20T12:00:00.000Z",
      "updated_at": "2026-04-20T12:00:00.000Z"
    }
  ]
}
 Related endpoints
POSTCreate an SSO connection
GETGet an SSO connection
PATCHUpdate 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
POSTStart a test sign-in
GETRead a test sign-in
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