---
title: "Register Sso Connection"
method: POST
path: "/api/v1/organizations/current/sso-connections"
tags: ["authed"]
---

# Register Sso Connection

`POST /api/v1/organizations/current/sso-connections`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/organizations/current/sso-connections`
- Auth: none declared

Create the domain's one connection, born active: GoTrue registers
the SAML provider from the IdP metadata and associates the domain,
and the row lands already carrying the provider id. The Supabase
call runs after every local precondition, with the session's
transaction released around it (db/engine.py's standing rule: never
hold a DbSession across a slow await) — the domain is re-read on the
write side, so a claim revoked during the wire call still refuses.

## Request body

- RegisterSsoConnectionRequest: The IdP half a registration carries: bounded opaque strings — Supabase is the arbiter of IdP metadata, so no shape check beyond length belongs here. Both metadata fields are optional in the schema but registration requires exactly one: a URL GoTrue re-fetches (preferred — IdP signing-cert rotation keeps working), or the metadata XML itself for IdPs that publish only a file. The XML bound is 256 KiB — real descriptors run ~4 KB (Google) to ~100 KB (ADFS).
  - `email_domain_id` string, uuid, required
  - `metadata_url` string, nullable
  - `metadata_xml` string, nullable
  - `entity_id` string, nullable

## Response `201`

Successful Response

- SsoConnectionResponse
  - `id` string, uuid, required
  - `email_domain_id` string, uuid, required
  - `status` 'pending' | 'active' | 'disabled', required: The connection lifecycle (the CHECK's mirror). pending awaits Supabase provider registration; active is a live federation anchored to a dns_verified domain; disabled withdraws federation — from active, or from a pending row abandoned before a provider ever existed — without erasing the row.
  - `sso_required` boolean, required
  - `metadata_url` string, nullable, required
  - `entity_id` string, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: The domain is not dns_verified, or already has its connection
- `422`: Not exactly one of metadata_url/metadata_xml was supplied, or Supabase rejected the IdP metadata
- `500`: Internal server error
- `502`: Supabase's admin API was unreachable
- `503`: SSO provider registration is not configured here

---

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