Organization Settings

Configure SMTP email delivery, custom domains, and branding for your organization.

SMTP Configuration

Custom SMTP settings for sending authentication emails with your domain.

Endpoints

Method	Path	Description
`POST`	`/api/organizations/:slug/smtp`	Configure SMTP
`GET`	`/api/organizations/:slug/smtp`	Get SMTP config
`DELETE`	`/api/organizations/:slug/smtp`	Remove SMTP config

POST /api/organizations/:slug/smtp

Configure custom SMTP settings.

Authorization: Owner or Admin

Request Body

Field	Type	Required	Description
`host`	`string`	Yes	SMTP server hostname
`port`	`integer`	Yes	SMTP port (25, 465, 587)
`username`	`string`	Yes	SMTP username
`password`	`string`	Yes	SMTP password
`from_email`	`string`	Yes	Sender email address
`from_name`	`string`	No	Sender display name

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/smtp \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "apikey",
    "password": "SG.xxxxx",
    "from_email": "noreply@acme.com",
    "from_name": "Acme Team"
  }'

GET /api/organizations/:slug/smtp

Get current SMTP configuration.

Response (200 OK)

{
  "host": "smtp.sendgrid.net",
  "port": 587,
  "username": "apikey",
  "from_email": "noreply@acme.com",
  "from_name": "Acme Team",
  "configured": true
}

[!NOTE] Password is never returned in responses.

Custom Domain

Configure a custom domain for white-label authentication.

Endpoints

Method	Path	Description
`POST`	`/api/organizations/:slug/domain`	Set domain
`POST`	`/api/organizations/:slug/domain/verify`	Verify domain
`GET`	`/api/organizations/:slug/domain`	Get domain config
`DELETE`	`/api/organizations/:slug/domain`	Remove domain

POST /api/organizations/:slug/domain

Set a custom domain.

Authorization: Owner or Admin

Request Body

Field	Type	Required	Description
`domain`	`string`	Yes	Custom domain (e.g., `auth.acme.com`)

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/domain \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{"domain": "auth.acme.com"}'

Response (200 OK)

{
  "domain": "auth.acme.com",
  "verified": false,
  "verification_token": "authos-verify=abc123def456",
  "verification_method": "dns_txt"
}

DNS Verification

Add a TXT record to verify domain ownership:

_authos-verify.auth.acme.com TXT "authos-verify=abc123def456"

POST /api/organizations/:slug/domain/verify

Verify domain ownership via DNS.

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/domain/verify \
  -H "Authorization: Bearer {jwt}"

Response - Success (200 OK)

{
  "domain": "auth.acme.com",
  "verified": true,
  "verified_at": "2025-01-15T10:30:00Z"
}

Response - Not Verified (400 Bad Request)

{
  "error": "DNS verification failed. Please ensure the TXT record is properly configured.",
  "expected_record": "_authos-verify.auth.acme.com",
  "expected_value": "authos-verify=abc123def456"
}

Branding

Customize the authentication UI with your brand.

Endpoints

Method	Path	Description
`PATCH`	`/api/organizations/:slug/branding`	Update branding
`GET`	`/api/organizations/:slug/branding`	Get branding
`GET`	`/api/organizations/:slug/branding/public`	Get public branding

PATCH /api/organizations/:slug/branding

Update organization branding.

Authorization: Owner or Admin

Request Body

Field	Type	Required	Description
`logo_url`	`string`	No	URL to logo image
`primary_color`	`string`	No	Primary color (hex, e.g., `#FF5733`)

Example Request

curl -X PATCH https://sso.example.com/api/organizations/acme-corp/branding \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "logo_url": "https://cdn.acme.com/logo.png",
    "primary_color": "#0066FF"
  }'

Response (200 OK)

{
  "logo_url": "https://cdn.acme.com/logo.png",
  "primary_color": "#0066FF"
}

GET /api/organizations/:slug/branding/public

Get branding without authentication (for login pages).

Authentication: None required

Response (200 OK)

{
  "organization_name": "Acme Corporation",
  "logo_url": "https://cdn.acme.com/logo.png",
  "primary_color": "#0066FF"
}

Risk Settings

Configure the risk engine thresholds and enforcement mode for your organization.

Endpoints

Method	Path	Description
`GET`	`/api/organizations/:slug/risk-settings`	Get risk settings
`PUT`	`/api/organizations/:slug/risk-settings`	Update risk settings
`POST`	`/api/organizations/:slug/risk-settings/reset`	Reset to defaults
`GET`	`/api/organizations/:slug/risk-events`	List risk events

GET /api/organizations/:slug/risk-settings

Get current risk engine configuration.

Authorization: Owner or Admin

Response (200 OK)

{
  "enforcement_mode": "log_only",
  "low_threshold": 30,
  "medium_threshold": 70,
  "new_device_score": 20,
  "impossible_travel_score": 50,
  "velocity_threshold": 10,
  "velocity_score": 30
}

PUT /api/organizations/:slug/risk-settings

Update risk engine settings. All fields are optional.

Authorization: Owner or Admin

Request Body

Field	Type	Constraints	Description
`enforcement_mode`	`string`	`log_only`, `monitor`, `challenge`, `block`	Risk engine mode
`low_threshold`	`integer`	0-100, must be < medium	Low risk threshold
`medium_threshold`	`integer`	0-100, must be > low	Medium risk threshold
`new_device_score`	`integer`	0-100	Score added for new devices
`impossible_travel_score`	`integer`	0-100	Score for impossible travel
`velocity_threshold`	`integer`	> 0	Max logins per minute
`velocity_score`	`integer`	0-100	Score for velocity violations

Example Request

curl -X PUT https://sso.example.com/api/organizations/acme-corp/risk-settings \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement_mode": "challenge",
    "medium_threshold": 60
  }'

Response (200 OK)

{
  "message": "Risk settings updated successfully",
  "settings": {
    "enforcement_mode": "challenge",
    "low_threshold": 30,
    "medium_threshold": 60,
    "new_device_score": 20,
    "impossible_travel_score": 50,
    "velocity_threshold": 10,
    "velocity_score": 30
  }
}

POST /api/organizations/:slug/risk-settings/reset

Reset all risk settings to default values.

Authorization: Owner or Admin

Example Request

curl -X POST https://sso.example.com/api/organizations/acme-corp/risk-settings/reset \
  -H "Authorization: Bearer {jwt}"

GET /api/organizations/:slug/risk-events

List login events with risk scores.

Authorization: Owner or Admin

Query Parameters

Parameter	Type	Default	Description
`page`	`integer`	`0`	Page number
`limit`	`integer`	`50`	Results per page (max 100)
`min_score`	`integer`	`0`	Minimum risk score filter

Response (200 OK)

[
  {
    "id": "event-uuid",
    "user_id": "user-uuid",
    "user_email": "user@example.com",
    "created_at": "2025-01-15T10:30:00Z",
    "risk_score": 45,
    "risk_factors": ["new_device", "new_ip"],
    "geo_country": "US",
    "geo_city": "San Francisco",
    "ip_address": "192.168.1.1",
    "provider": "github"
  }
]

Enforcement Modes

Mode	Behavior
`log_only`	Log risk scores without taking action
`monitor`	Log and alert on high-risk events
`challenge`	Require MFA for medium/high risk logins
`block`	Block high-risk logins entirely