---
title: "Start a federated-login configuration test (owner)"
method: POST
path: "/v1/organizations/{organization_id}/sso/test"
tags: ["organizations"]
---

# Start a federated-login configuration test (owner)

`POST /v1/organizations/{organization_id}/sso/test`

## Request

- Base URL: `https://api.ethiack.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ethiack.com/v1/organizations/{organization_id}/sso/test`
- Auth: none declared

Hand back a real login ceremony to run against the customer's own IdP.

The safety net under ``PUT .../sso/policy``: every interlock there proves
the configuration is *coherent*, and none of them proves the customer's IdP
answers. An owner who turns on ``require_sso`` against a connection that
does not work locks out an organization whose members hold no password.

``POST`` because it creates an intent in Zitadel, and no body because the
only input is the connection, which the path already names. Answers 400 for
a connection no admin has pointed anywhere, and 503 when this deployment
configured no return URLs.

Args:
    organization_id (int): The parent organization.
    db (AsyncSession): Request-scoped session.
    context (ActiveContext): Resolved caller.

Returns:
    SsoTestStartResponse: A redirect URL or a form to POST, depending on the
        provider's binding.

## Path parameters

- `organization_id` integer, required

## Response `200`

Successful Response

- SsoTestStartResponse: What the front-end must do next to run the ceremony. Not a bare URL. SAML's HTTP-POST binding returns a signed request to submit rather than an address to follow, so a caller that reads only ``auth_url`` works for OIDC and for HTTP-Redirect SAML and silently does nothing for a template set to POST. Phoenix mints HTTP-Redirect, but a template minted before that, or edited in the Zitadel console, can still answer with a form.
  - `step` 'redirect' | 'form_post', required: How the browser reaches the provider. Not a caller's choice: it is decided by the template's binding. Phoenix mints every SAML template with HTTP-Redirect, because the login app can only follow a URL, so a form arrives only for a template set to POST some other way -- one minted before that, or edited in the Zitadel console. Handled all the same. Attributes: REDIRECT: Navigate to a URL. OIDC, and SAML over HTTP-Redirect. FORM_POST: POST a form. SAML over HTTP-POST, where the signed request travels in a field and there is no URL to follow.
  - `auth_url` string, nullable: Navigate the browser here. Set only when step is `redirect`.
  - `form_url` string, nullable: POST the form here. Set only when step is `form_post`.
  - `form_fields` object: Fields to POST, empty for a redirect. Submit every one as-is and as `type="text"`; they carry the signed `SAMLRequest`.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ethiack/apis/ethiack-api.md) - [All operations](https://skmtc.dev/ethiack/apis/ethiack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ethiack/apis/ethiack-api/revisions/4eaba89bfebf?raw)