Settings & Configuration

Manage instance-level configuration including branding, security policies, and initial onboarding.

GET/api/v1/settingsGet instance settingsBearer Token▾

Returns the current instance settings including name, branding, allowed domains, MFA requirements, and custom login configuration.

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Singleton identifier (always "singleton").
`name`	string	Optional	Instance display name.
`logoUrl`	string \| null	Optional	Public URL of the instance logo.
`primaryColor`	string	Optional	Brand hex color used in hosted UI.
`allowedDomains`	string[]	Optional	Email domains permitted for self-service sign-up.
`mfaRequired`	boolean	Optional	Whether MFA is mandatory for all users.
`mfaGracePeriodDays`	number	Optional	Number of days users have to enroll MFA after it becomes required.
`customLoginConfig`	object \| null	Optional	Custom login page configuration (headline, subtitle, background).
`createdAt`	string	Optional	ISO 8601 creation timestamp.
`updatedAt`	string	Optional	ISO 8601 last-update timestamp.

Response Example

{
  "id": "singleton",
  "name": "Acme Corp",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com",
    "acme.io"
  ],
  "mfaRequired": true,
  "mfaGracePeriodDays": 7,
  "customLoginConfig": {
    "headline": "Welcome to Acme",
    "subtitle": "Sign in to your account"
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-06-15T10:30:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/settings" \
  -H "Authorization: Bearer <your_token>"

PUT/api/v1/settingsUpdate instance settingsBearer Token▾

Updates branding, security, and login customization settings for the instance. Only provided fields are changed.

Request Body

Name	Type	Required	Description
`name`	string	Optional	Instance display name.e.g. `Acme Corp`
`logoUrl`	string	Optional	Public URL of the instance logo.e.g. `https://cdn.acme.com/logo.png`
`primaryColor`	string	Optional	Brand hex color used in hosted UI.e.g. `#0057FF`
`customLoginConfig`	object	Optional	Custom login page configuration (headline, subtitle, background image, etc.).e.g. `{"headline":"Welcome","subtitle":"Sign in"}`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Singleton identifier.
`name`	string	Optional	Updated instance name.
`logoUrl`	string \| null	Optional	Updated logo URL.
`primaryColor`	string	Optional	Updated brand color.
`customLoginConfig`	object \| null	Optional	Updated login page configuration.
`updatedAt`	string	Optional	ISO 8601 timestamp of the update.

Response Example

{
  "id": "singleton",
  "name": "Acme Corp",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com"
  ],
  "mfaRequired": true,
  "mfaGracePeriodDays": 7,
  "customLoginConfig": {
    "headline": "Welcome",
    "subtitle": "Sign in"
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-06-15T12:00:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/settings" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "primaryColor": "#0057FF",
    "customLoginConfig": {
      "headline": "Welcome to Acme",
      "subtitle": "Sign in to continue"
    }
  }'

GET/api/v1/configGet application configurationBearer Token▾

Returns the full application configuration including all branding, security, and domain settings. Requires org:read permission.

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Singleton identifier.
`name`	string	Optional	Instance name.
`logoUrl`	string \| null	Optional	Logo URL.
`primaryColor`	string	Optional	Primary brand color.
`allowedDomains`	string[]	Optional	Permitted email domains for sign-up.
`mfaRequired`	boolean	Optional	Whether MFA is mandatory.
`mfaGracePeriodDays`	number	Optional	Grace period for MFA enrollment.
`customLoginConfig`	object \| null	Optional	Custom login page configuration.
`createdAt`	string	Optional	ISO 8601 creation timestamp.
`updatedAt`	string	Optional	ISO 8601 last-update timestamp.

Response Example

{
  "id": "singleton",
  "name": "SutraID",
  "logoUrl": null,
  "primaryColor": "#000000",
  "allowedDomains": [],
  "mfaRequired": false,
  "mfaGracePeriodDays": 7,
  "customLoginConfig": null,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/config" \
  -H "Authorization: Bearer <your_token>"

PUT/api/v1/configUpdate application configurationBearer Token▾

Updates the application configuration. Supports partial updates — only the provided fields are changed. Read-only fields (id, createdAt, updatedAt) are automatically stripped.

Request Body

Name	Type	Required	Description
`name`	string	Optional	Instance display name.e.g. `My SutraID Instance`
`logoUrl`	string	Optional	Public URL of the instance logo.e.g. `https://cdn.example.com/logo.png`
`primaryColor`	string	Optional	Brand hex color.e.g. `#1A73E8`
`allowedDomains`	string[]	Optional	List of email domains permitted for user sign-up.e.g. `["example.com","corp.example.com"]`
`mfaRequired`	boolean	Optional	Enable or disable mandatory MFA for all users.e.g. `true`
`mfaGracePeriodDays`	number	Optional	Number of days users have to enroll MFA after it becomes required.e.g. `14`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Singleton identifier.
`name`	string	Optional	Updated instance name.
`primaryColor`	string	Optional	Updated brand color.
`allowedDomains`	string[]	Optional	Updated allowed domains.
`mfaRequired`	boolean	Optional	Updated MFA requirement.
`mfaGracePeriodDays`	number	Optional	Updated grace period.
`updatedAt`	string	Optional	ISO 8601 timestamp of the update.

Response Example

{
  "id": "singleton",
  "name": "My SutraID Instance",
  "logoUrl": "https://cdn.example.com/logo.png",
  "primaryColor": "#1A73E8",
  "allowedDomains": [
    "example.com",
    "corp.example.com"
  ],
  "mfaRequired": true,
  "mfaGracePeriodDays": 14,
  "customLoginConfig": null,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-06-20T08:00:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/config" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SutraID Instance",
    "allowedDomains": ["example.com"],
    "mfaRequired": true,
    "mfaGracePeriodDays": 14
  }'

POST/api/v1/onboardInitial instance onboarding▾

Bootstraps a new SutraID instance by creating the first super-admin user and initializing default configuration. A magic link is sent to the provided email. This endpoint can only be called once — subsequent calls will fail with a 409 Conflict.

Request Body

Name	Type	Required	Description
`adminEmail`	string	Required	Email address for the initial super-admin account.e.g. `admin@acme.com`

Response Fields

Name	Type	Required	Description
`message`	string	Optional	Confirmation message.
`user.id`	string	Optional	Unique identifier of the created admin user.
`user.email`	string	Optional	Email address of the admin.
`user.role`	string	Optional	Assigned role (always SUPER_ADMIN).

Response Example

{
  "message": "Onboarding complete. Magic link sent to admin email.",
  "user": {
    "id": "usr_01hx9z1q2w3e4r5t6y7u",
    "email": "admin@acme.com",
    "role": "SUPER_ADMIN"
  }
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/onboard" \
  -H "Content-Type: application/json" \
  -d '{
    "adminEmail": "admin@acme.com"
  }'

GET/api/v1/stats/active-sessionsGet active session countBearer Token▾

Returns the count of users who have logged in within the last 24 hours. Useful for dashboard metrics and monitoring.

Response Fields

Name	Type	Required	Description
`activeSessions`	number	Optional	Number of users active in the last 24 hours.
`periodHours`	number	Optional	Time window in hours (always 24).

Response Example

{
  "activeSessions": 127,
  "periodHours": 24
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/stats/active-sessions" \
  -H "Authorization: Bearer <your_token>"