> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Features
> Toggle feature flags on a SIS environment to choose which Sumvin behaviors apply to your users.
# 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](#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 IPA 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`](/concepts/onboarding-state-machine).
* 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
```bash theme={null}
curl -X PUT "https://sis.sumvin.com/v0/organisation/{org_id}/environments/{env_id}/features/kyc" \
-H "Authorization: Bearer " \
-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`**:
```json theme={null}
{
"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):
```json theme={null}
{
"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:
1. `PUT .../features/{currently_enabled}` with `{"enabled": false}` to disable the currently-active feature first.
2. `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:
```bash theme={null}
curl -X PUT "https://sis.sumvin.com/v0/organisation/{org_id}/environments/{env_id}/features/user_signed_deploy" \
-H "Authorization: Bearer " \
-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`.
## Related
* [Onboarding state machine](/concepts/onboarding-state-machine) — how features map to user-visible steps
* [Wallets guide](/guides/wallets) — Safe vs EOA semantics
* [Safe user operations](/guides/safe-user-operations) — the prepare/submit flow when `user_signed_deploy` is enabled