---
title: "Claim a domain"
method: POST
path: "/api/v1/sso/domains"
tags: ["Team"]
---

# Claim a domain

`POST /api/v1/sso/domains`

## Request

- Base URL: `http://localhost:5180`
- URL: `http://localhost:5180/api/v1/sso/domains`
- Auth: API key in cookie `better-auth.session_token`

Starts verifying a domain: the answer carries the TXT record to publish. Claiming one again before it is verified issues a new record. A domain another team has verified cannot be claimed.

## Request body

- object
  - `domain` string, required: The domain, such as `example.com`. A scheme, a path or an `@` in front is dropped.
  - `mode` 'auto_join' | 'restricted': `auto_join` puts anyone signing in with an address there on the team; `restricted` also requires them to sign in through the provider.

## Response `200`

Single sign-on for this team as it stands.

- object
  - `ok` unknown, required
  - `data` object, required
    - `protocol` 'saml' | 'oidc', required
    - `enabled` boolean, required: Whether people on the verified domains sign in through the provider.
    - `saml` object, required
      - `ssoUrl` string, nullable, required
      - `idpEntityId` string, nullable, required
      - `certificate` string, nullable, required: The provider’s signing certificate, as PEM. A response not signed by it is refused.
    - `oidc` object, required
      - `issuer` string, nullable, required
      - `clientId` string, nullable, required
      - `clientSecretSet` boolean, required: Whether a client secret is stored. The secret itself is never returned.
    - `serviceProvider` object, required
      - `entityId` string, required
      - `acsUrl` string, required
      - `metadataUrl` string, required
      - `redirectUri` string, required
    - `domains` object[], required
      - `domain` string, required: The domain, lower case, with no scheme or `@`.
      - `mode` 'auto_join' | 'restricted', required: `auto_join` puts anyone signing in with an address there on the team; `restricted` also requires them to sign in through the provider while it is switched on.
      - `verified` boolean, required: Whether the DNS record has been found. Until it has, the domain does nothing.
      - `txtHost` string, required: The name to publish the TXT record under.
      - `txtValue` string, required: The value the TXT record must hold.
    - `updatedAt` string, nullable, required: ISO 8601 timestamp.
    - `signedOut` number: How many people this change signed out, because their domain now signs in only through the provider. Present only when it signed somebody out.
  - `meta` object, required
    - `requestId` string, required: Echoed in the x-request-id header. Quote it in a bug report.

## Other responses

- `403`: Not an owner of this team.
- `409`: Another team has verified this domain.
- `422`: Not a domain.

---

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