Environment features

Each SIS environment has a set of feature flags that control which Sumvin behaviors apply to users authenticated under that environment. Features are scoped per-environment so dev / staging / prod can run with different cohorts during a rollout. Features live under Environment → Features in the dashboard, and over the SIS API at:

PUT    /v0/organisation/{org_id}/environments/{env_id}/features/{slug}
GET    /v0/organisation/{org_id}/environments/{env_id}/features/{slug}
GET    /v0/organisation/{org_id}/environments/{env_id}/features?scope=available
DELETE /v0/organisation/{org_id}/environments/{env_id}/features/{slug}

?scope=available returns the full catalogue with each feature’s current enabled status; ?scope=enabled (the default) returns only features that are explicitly enabled.

Available features

Slug	Description
`kyc`	Always required. Identity verification for every Sumvin developer — the dashboard hides the enable/disable toggle. The `config` field selects the verification mode (see Always-required features below).
`ai_agent`	Sumvin’s signing service deploys a Safe smart wallet for the user, with an agent signer attached. The agent can sign UserOps on the user’s behalf inside guardrails set by your configuration. Default cohort.
`user_signed_deploy`	Recommended for developers who want user-controlled wallets. The user signs the Safe-deployment UserOp themselves; Sumvin sponsors gas. The deployed Safe has the user’s EOA as its sole owner — no agent signer is attached, and Sumvin can never sign on it. Mutually exclusive with `ai_agent`.
`crypto_wallet_card`	Issue a debit card funded from the user’s Safe.
`gasless_wallet_rails`	Sponsor gas for wallet UserOps (cards, IPAs, etc.).
`virtual_iban`	Issue a per-user IBAN for fiat on/off-ramp.
`ai_advisor`	Enable conversational AI insights on the user’s portfolio.

Always-required features

A small number of features are required for every Sumvin developer. The dashboard renders them with a Required badge instead of an enable/disable switch and auto-upserts enabled: true on first visit so the row is always present and editable. Today the only always-required feature is kyc. The behavior is:

KYC verification is part of the onboarding state machine for every user — developers cannot disable it. The enabled flag on the feature row is always true; the dashboard does not expose a toggle.

The config field selects the mode — how the SDK and your client share responsibility for identity verification. Allowed values:

Mode	`config.mode`	What it does
WebSDK (default)	`websdk`	Embedded SDK handles documents, selfie, and liveness end-to-end.
Hybrid	`hybrid`	Your client uploads documents via the API; SDK runs liveness only.
Document Only	`document_only`	Your client uploads documents via the API; no SDK is launched.

Mode resolution at runtime is per environment, with a configurable global default:
1. If a row exists for the user’s environment with a recognised config.mode, that value is used.
2. Otherwise the resolver falls back to a global default verification mode. This default is itself configurable and may be set to any of websdk, hybrid, or document_only — it is not fixed to websdk.
3. An unrecognised config.mode value is ignored; resolution continues to the global default in step 2.
The mode appears on the kyc_verification onboarding step’s meta.kyc_mode field so clients render the right flow. See OnboardingStep.KYC_VERIFICATION.
The dashboard treats an explicit config.mode = "websdk" as the reset-to-baseline value. This only coincides with “no override” when the global default is also websdk; because that default is configurable, the two are not always equivalent.

Setting the KYC mode

curl -X PUT "https://sis.sumvin.com/v0/organisation/{org_id}/environments/{env_id}/features/kyc" \
  -H "Authorization: Bearer <your-dashboard-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "config": { "mode": "hybrid" }
  }'

Sending {"enabled": false} for kyc is permitted at the API layer for operational symmetry but will not skip the KYC step for users — the onboarding state machine ignores the enabled flag for kyc and only reads config.mode. The dashboard never sends enabled: false for required features. Validation errors on config.mode return 422 with error code KYC-422-001:

{
  "type": "https://api.sumvin.com/errors/kyc-422-001",
  "title": "Invalid KYC configuration",
  "status": 422,
  "detail": "config.mode must be one of: websdk, hybrid, document_only",
  "error_code": "KYC-422-001"
}

Mutual exclusivity: `ai_agent` vs `user_signed_deploy`

These two features are mutually exclusive at the environment level. They drive completely different Safe-deployment paths and onboarding cohorts:

ai_agent (default): Sumvin deploys the Safe; an agent signer is attached and authorised to sign UserOps for the user.
user_signed_deploy (recommended non-default): The user deploys the Safe themselves; only their EOA is an owner. Sumvin can never sign on the resulting Safe.

Trying to enable both returns 409 Conflict with error code SIS-409-008 (Feature Mutex Violation):

{
  "type": "https://api.sumvin.com/errors/sis-409-008",
  "title": "Feature Mutex Violation",
  "status": 409,
  "detail": "Cannot enable 'ai_agent' while 'user_signed_deploy' is also enabled. These features are mutually exclusive — disable 'user_signed_deploy' first.",
  "error_code": "SIS-409-008"
}

To switch between the two for an environment:

PUT .../features/{currently_enabled} with {"enabled": false} to disable the currently-active feature first.
PUT .../features/{the_other} with {"enabled": true} to enable the new one.

The mutex is enforced at write-time. If neither is enabled, the user’s onboarding routes through the byo_safe step instead (BYO — Bring Your Own Safe — the user submits the address of a Safe they already control on-chain). This is the legacy fallback for developers with existing Safe infrastructure.

This mutex enforces a per-environment policy decision. Don’t toggle these flags mid-flow for users already onboarded — switching from ai_agent to user_signed_deploy doesn’t migrate existing wallets, and existing agent-managed Safes will remain agent-managed.

Onboarding cohort summary

The ai_agent / user_signed_deploy choice picks which onboarding step a user runs. Three valid cohorts:

Cohort	`ai_agent`	`user_signed_deploy`	`byo_safe` step	`safe_deploy` step	Result
Agent-managed (default)	enabled	disabled	skipped	skipped	Sumvin’s signing service deploys the Safe automatically and attaches an agent signer.
User-signed deploy (recommended non-default)	disabled	enabled	skipped	required	User signs the deploy UserOp via Sumvin’s prepare/submit endpoints. Sumvin sponsors gas; user’s EOA is the sole owner.
BYO Safe (legacy)	disabled	disabled	required	skipped	User submits the address of an existing on-chain Safe they already control.
Rejected at write	enabled	enabled	—	—	`SIS-409-008` Feature Mutex Violation.

Users that have no org_id (non-SIS-managed users) skip both byo_safe and safe_deploy. When picking a cohort:

Default to ai_agent unless your integration explicitly needs user-controlled keys.
Choose user_signed_deploy if your users must hold sole ownership of their Safe (e.g. compliance, custodial neutrality, or self-custody product positioning).
Choose byo_safe only if you already have an on-chain Safe deployment infrastructure and want users to pre-deploy their Safes outside Sumvin.

Setting a feature

The feature endpoints under /v0/organisation/{org_id}/environments/{env_id}/features/ are dashboard-scoped — they authenticate with your dashboard session token used by the SIS Dashboard, not the API keys used by SIS verifier traffic. Most developers will toggle features through the dashboard UI; the underlying call looks like:

curl -X PUT "https://sis.sumvin.com/v0/organisation/{org_id}/environments/{env_id}/features/user_signed_deploy" \
  -H "Authorization: Bearer <your-dashboard-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "config": null
  }'

A new feature returns 201 Created; a flip on an existing feature returns 200 OK. The mutex (above) is enforced on enabled: true only — disabling never returns SIS-409-008.

Onboarding state machine — how features map to user-visible steps
Wallets guide — Safe vs EOA semantics
Safe user operations — the prepare/submit flow when user_signed_deploy is enabled

​Environment features

​Available features

​Always-required features

​Setting the KYC mode

​Mutual exclusivity: ai_agent vs user_signed_deploy

​Onboarding cohort summary

​Setting a feature

​Related

Environment features

Available features

Always-required features

Setting the KYC mode

Mutual exclusivity: `ai_agent` vs `user_signed_deploy`

Onboarding cohort summary

Setting a feature

Related