Settings API

The Settings API lets you read and update your workspace's configuration programmatically. Settings are organized into four categories: signing behavior, email notifications, AI features, and security.

The Settings Object

Attributes

{
  "signing": {
    "allowed_signature_types": ["draw", "type", "upload"],
    "default_deadline_days": 30,
    "esign_consent_text": null
  },
  "notifications": {
    "reminder_schedule": [3, 7, 14],
    "expiration_alert_days": 3,
    "send_completion_email": true,
    "send_viewed_notification": true
  },
  "ai": {
    "enabled": false,
    "auto_analyze": false
  },
  "security": {
    "ip_allowlist": [],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": null
  }
}

Signing Settings

Field	Type	Description
`allowed_signature_types`	string[]	Accepted methods: `draw`, `type`, `upload`
`default_deadline_days`	number	Days until a sent document expires (1–365, default 30)
`esign_consent_text`	string	Custom ESIGN Act consent text shown before signing (`null` = default)

Notification Settings

Field	Type	Description
`reminder_schedule`	number[]	Days after sending to auto-send reminders (e.g., `[3, 7, 14]`)
`expiration_alert_days`	number	Days before deadline to send an expiration warning (1–30)
`send_completion_email`	boolean	Notify the document owner when all parties have signed
`send_viewed_notification`	boolean	Notify the owner when a recipient opens the document

AI Settings

Field	Type	Description
`enabled`	boolean	Whether AI features are enabled for the workspace
`auto_analyze`	boolean	Automatically analyze new documents with AI

Security Settings

Field	Type	Description
`ip_allowlist`	string[]	Allowed IP ranges in CIDR notation (empty = all IPs allowed)
`allow_api_access`	boolean	Whether API key access is enabled for the workspace
`require_mfa`	boolean	Require multi-factor authentication for all members
`session_timeout_minutes`	number	Session timeout in minutes (`null` = browser default)

Get Settings

Retrieve the current workspace configuration.

Endpoint

GET /api/v1/settings

Required Scope

seal:settings:read

TypeScript Example

const response = await fetch("https://seal.convex.site/api/v1/settings", {
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
  },
});

const settings = await response.json();
console.log(settings.signing.default_deadline_days); // 30

cURL Example

curl -X GET "https://seal.convex.site/api/v1/settings" \
  -H "Authorization: Bearer ak_your_api_key_here"

Response

{
  "signing": {
    "allowed_signature_types": ["draw", "type", "upload"],
    "default_deadline_days": 30,
    "esign_consent_text": null
  },
  "notifications": {
    "reminder_schedule": [3, 7, 14],
    "expiration_alert_days": 3,
    "send_completion_email": true,
    "send_viewed_notification": true
  },
  "ai": {
    "enabled": false,
    "auto_analyze": false
  },
  "security": {
    "ip_allowlist": [],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": null
  }
}

Update Settings

Update workspace configuration. All fields in all categories are optional — only the fields you include are changed. Categories you omit are left untouched.

Endpoint

PATCH /api/v1/settings

Required Scope

seal:settings:write

Request Body

All fields are optional. Include only the categories and fields you want to change.

{
  "signing": {
    "allowed_signature_types": ["draw", "type"],
    "default_deadline_days": 14,
    "esign_consent_text": "I agree to sign this document electronically."
  },
  "notifications": {
    "reminder_schedule": [3, 7],
    "expiration_alert_days": 5,
    "send_completion_email": true,
    "send_viewed_notification": false
  },
  "ai": {
    "enabled": true,
    "auto_analyze": true
  },
  "security": {
    "ip_allowlist": ["10.0.0.0/8", "192.168.1.0/24"],
    "allow_api_access": true,
    "require_mfa": false,
    "session_timeout_minutes": 480
  }
}

TypeScript Example

// Update only signing settings — everything else is preserved
const response = await fetch("https://seal.convex.site/api/v1/settings", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    signing: {
      default_deadline_days: 14,
      allowed_signature_types: ["draw", "type"],
    },
  }),
});

const result = await response.json();
// { "success": true }

cURL Example

curl -X PATCH "https://seal.convex.site/api/v1/settings" \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": {
      "send_viewed_notification": false
    }
  }'

Response

{
  "success": true
}

Partial updates: You can update a single field inside a category without specifying the rest. For example, setting only signing.default_deadline_days leaves allowed_signature_types and esign_consent_text unchanged.

Clearing a field: To clear esign_consent_text or session_timeout_minutes, pass null explicitly. Omitting the field preserves the current value.

Next Steps

Members API - View workspace members
Audit Log API - Audit setting changes
Documents API - Manage documents

Settings API

On this page