Sign-in API

10 operations. Paths are relative to the API host (http://localhost:5080 in local development). Every operation accepts an OIDC bearer token (Authorization: Bearer …) or a workspace API key (X-Api-Key: keel_live_…); errors are RFC 9457 Problem Details with a code (error codes). Permissions: matrix.

Method	Path	Summary
GET	/api/v1/signin/discover	Home-realm discovery: the IdP alias (kc_idp_hint) of a verified work-email domain, or null for the default sign-in.
GET	/api/v1/signin/options	What the sign-in page offers: sign-up mode (SalesLed | SelfServe), social brokers, magic link, the demo form and the sales address.
POST	/api/v1/signup	Self-serve sign-up step 1 (Keel:Signup:Mode = SelfServe): emails a one-time verification link. 202; 403 Identity.SignupClosed when sales-led.
POST	/api/v1/signup/complete	Sign-up step 3: company and region → IdP account (no password stored by Keel), tenant, Owner, trial; the IdP emails a set-password link.
POST	/api/v1/signup/verify	Sign-up step 2: opens the emailed link (single use, 30 min) and returns a completion token for this browser.
GET	/api/v1/tenant/sso-domains	Single sign-on domains of the tenant with their DNS TXT challenge (Owners).
POST	/api/v1/tenant/sso-domains	Map an email domain to the tenant's identity provider (Keycloak alias). Unverified until the TXT record is found.
PATCH	/api/v1/tenant/sso-domains/{domainId}	Change the identity provider a domain signs in with.
DELETE	/api/v1/tenant/sso-domains/{domainId}	Remove a single sign-on domain.
POST	/api/v1/tenant/sso-domains/{domainId}:verify	Check the domain's DNS TXT record (_keel-challenge.<domain>) and mark it verified.

DiscoverIdentityProvider

GET /api/v1/signin/discover

Home-realm discovery: the IdP alias (kc_idp_hint) of a verified work-email domain, or null for the default sign-in.

Parameter	In	Type	Required	Notes
email	query	string	yes

Status	Description	Body
200	OK	IdentityProviderDiscovery

Response 200: IdentityProviderDiscovery

Field	Type	Notes
idpHint	string?

GetSignInOptions

GET /api/v1/signin/options

What the sign-in page offers: sign-up mode (SalesLed | SelfServe), social brokers, magic link, the demo form and the sales address.

Status	Description	Body
200	OK	SignInOptionsResponse

Response 200: SignInOptionsResponse

Field	Type	Notes
demoUrl	string
magicLink	boolean
magicLinkIdpHint	string?
salesEmail	string
signupMode	string
socialProviders	string[]
turnstileSiteKey	string?

StartSignup

POST /api/v1/signup

Self-serve sign-up step 1 (Keel:Signup:Mode = SelfServe): emails a one-time verification link. 202; 403 Identity.SignupClosed when sales-led.

Request body (application/json): StartSignupRequest

Field	Type	Notes
email	string?
turnstileToken	string?
website	string?	Honeypot: a field hidden from people. Leave it empty.

Status	Description	Body
202	Accepted	—
400	Bad Request	ProblemDetails
403	Forbidden	ProblemDetails
429	Too Many Requests	ProblemDetails

CompleteSignup

POST /api/v1/signup/complete

Sign-up step 3: company and region → IdP account (no password stored by Keel), tenant, Owner, trial; the IdP emails a set-password link.

Request body (application/json): CompleteSignupRequest

Field	Type	Notes
companyName	string
completionToken	string
region	DataRegion	One of US, EU

Status	Description	Body
201	Created	CompletedSignupResponse

Response 201: CompletedSignupResponse

Field	Type	Notes
email	string
plan	string?
setPasswordEmailSent	boolean
tenantId	uuid
trialEndsAt	date-time?
workspaceId	uuid

VerifySignup

POST /api/v1/signup/verify

Sign-up step 2: opens the emailed link (single use, 30 min) and returns a completion token for this browser.

Request body (application/json): VerifySignupRequest

Field	Type	Notes
token	string

Status	Description	Body
200	OK	VerifiedSignupResponse

Response 200: VerifiedSignupResponse

Field	Type	Notes
completionToken	string
email	string
expiresAt	date-time

ListSsoDomains

GET /api/v1/tenant/sso-domains

Single sign-on domains of the tenant with their DNS TXT challenge (Owners).

Status	Description	Body
200	OK	SsoDomainDto[]

AddSsoDomain

POST /api/v1/tenant/sso-domains

Map an email domain to the tenant's identity provider (Keycloak alias). Unverified until the TXT record is found.

Request body (application/json): AddSsoDomainRequest

Field	Type	Notes
domain	string
idpAlias	string?	A Keycloak IdP alias; omit it to use the tenant's own SSO connection (Settings › SSO & SCIM).

Status	Description	Body
201	Created	CreatedResponse

Response 201: CreatedResponse

Field	Type	Notes
id	uuid

ChangeSsoDomainIdp

PATCH /api/v1/tenant/sso-domains/{domainId}

Change the identity provider a domain signs in with.

Parameter	In	Type	Required	Notes
domainId	path	uuid	yes

Request body (application/json): ChangeSsoDomainIdpRequest

Field	Type	Notes
idpAlias	string

Status	Description	Body
204	No Content	—

RemoveSsoDomain

DELETE /api/v1/tenant/sso-domains/{domainId}

Remove a single sign-on domain.

Parameter	In	Type	Required	Notes
domainId	path	uuid	yes

Status	Description	Body
204	No Content	—

VerifySsoDomain

POST /api/v1/tenant/sso-domains/{domainId}:verify

Check the domain's DNS TXT record (_keel-challenge.<domain>) and mark it verified.

Parameter	In	Type	Required	Notes
domainId	path	uuid	yes

Status	Description	Body
204	No Content	—