Settings API

Read domain, email, storage and single sign-on settings. Service account tokens only; changing settings is for people only. Every request sends a token in the Authorization: Bearer header; see Get started with the API.

List email setups

GET /api/admin/smtp-configs

Lists every email sending setup: SMTP servers and Microsoft 365 app registrations. Passwords and client secrets are never returned.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is array of SmtpConfig.

{
  "success": true,
  "data": [
    {
      "id": "3f1c2a9e-6b7d-4e21-9c0a-5d8e7f6a1b23",
      "name": "Company mail",
      "description": "Main relay",
      "is_default": true,
      "is_active": true,
      "provider": "smtp",
      "host": "smtp.example.com",
      "port": 587,
      "encryption": "starttls",
      "username": "dew@example.com",
      "password_set": true,
      "from_email": "files@example.com",
      "from_name": "Example Files",
      "created_at": "2026-09-14T08:12:00Z",
      "updated_at": "2026-09-20T10:03:41Z",
      "ms_client_secret_set": false
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get an email setup

GET /api/admin/smtp-configs/{id}

Returns one email sending setup. Passwords and client secrets are never returned.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Email setup ID.

Response 200

data is SmtpConfig.

{
  "success": true,
  "data": {
    "id": "3f1c2a9e-6b7d-4e21-9c0a-5d8e7f6a1b23",
    "name": "Company mail",
    "description": "Main relay",
    "is_default": true,
    "is_active": true,
    "provider": "smtp",
    "host": "smtp.example.com",
    "port": 587,
    "encryption": "starttls",
    "username": "dew@example.com",
    "password_set": true,
    "from_email": "files@example.com",
    "from_name": "Example Files",
    "created_at": "2026-09-14T08:12:00Z",
    "updated_at": "2026-09-20T10:03:41Z",
    "ms_client_secret_set": false
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such item.	“SMTP configuration not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List SMS setups

GET /api/admin/sms-configs

Lists every text message provider setup. API keys are never returned. A Twilio setup that is in use but has no sender has needs_sender set.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is array of SmsConfig.

{
  "success": true,
  "data": [
    {
      "id": "8a2d4f60-1c3b-4e5a-9f7d-2b6c8e0a4d19",
      "name": "Twilio",
      "is_default": true,
      "is_active": true,
      "provider_type": "twilio",
      "api_key_set": true,
      "account_sid": "AC0123456789abcdef0123456789abcdef",
      "created_at": "2026-09-14T08:15:00Z",
      "updated_at": "2026-09-14T08:15:00Z"
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get an SMS setup

GET /api/admin/sms-configs/{id}

Returns one text message provider setup. API keys are never returned. needs_sender is only filled in by the list.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	SMS setup ID.

Response 200

data is SmsConfig.

{
  "success": true,
  "data": {
    "id": "8a2d4f60-1c3b-4e5a-9f7d-2b6c8e0a4d19",
    "name": "Twilio",
    "is_default": true,
    "is_active": true,
    "provider_type": "twilio",
    "api_key_set": true,
    "account_sid": "AC0123456789abcdef0123456789abcdef",
    "created_at": "2026-09-14T08:15:00Z",
    "updated_at": "2026-09-14T08:15:00Z"
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such item.	“SMS configuration not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get server-wide settings

GET /api/admin/global-settings

Returns the server-wide settings: storage, links, uploads, branding, email templates, security and alerts. Domains use these unless their own settings override them.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is GlobalSettings.

{
  "success": true,
  "data": {
    "storage_provider": "storage_default",
    "max_upload_size_gb": 200,
    "link_expiry_days": 30,
    "max_link_lifetime_days": null,
    "link_format_template": null,
    "blocked_file_extensions": [
      ".exe",
      ".bat"
    ],
    "upload_limit_per_ip_mbps": null,
    "upload_limit_total_mbps": null,
    "upload_limit_exempt_local": true,
    "enable_admin_ip_allowlist": false,
    "admin_dashboard_allowed_ips": [],
    "private_links_enabled": false,
    "smtp_config_id": "3f1c2a9e-6b7d-4e21-9c0a-5d8e7f6a1b23",
    "display_name": "Example Files",
    "has_logo": true,
    "logo_not_email_safe": false,
    "has_favicon": true,
    "has_background": false,
    "accent_color": "#2563eb",
    "email_invite_subject": null,
    "email_invite_title": null,
    "email_invite_body": null,
    "email_alert_subject": null,
    "email_alert_title": null,
    "email_alert_body": null,
    "email_footer": null,
    "audit_log_retention_days": 365,
    "received_file_retention_days": 30,
    "allow_link_file_requests": true,
    "require_link_upload_verification": true,
    "avatars_enabled": true,
    "personal_tokens_enabled": true,
    "email_configured": true,
    "disable_zip_browser": false,
    "sanitize_windows_filenames": true,
    "enable_sspr": true,
    "require_2fa": "admins",
    "password_policy_mode": "simple",
    "password_min_length": 12,
    "password_require_mixed_case": false,
    "password_require_number": false,
    "password_require_symbol": false,
    "password_regex": "^.{12,}$",
    "password_guidance": "At least 12 characters",
    "link_not_found_behavior": "informative",
    "link_not_found_redirect_url": null,
    "session_lifetime_hours": 168,
    "idle_timeout_enabled": false,
    "idle_timeout_hours": 8,
    "alert_cert_expiry_enabled": true,
    "alert_storage_enabled": true,
    "alert_storage_threshold_pct": 90,
    "alert_storage_health_enabled": true,
    "alert_license_enabled": true,
    "alert_email_provider_enabled": true,
    "alert_api_token_enabled": true,
    "alert_version_enabled": false,
    "update_check_enabled": true
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List certificate folders

GET /api/admin/certs

Lists the certificate folders on the server that a domain can use, sorted by name. Only file locations are returned, never certificate or key contents. Let’s Encrypt certificates are not listed here.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is array of CertificateFolder.

{
  "success": true,
  "data": [
    {
      "cert_name": "files.example.com",
      "cert_path": "certs/files.example.com/cert.pem",
      "key_path": "certs/files.example.com/key.pem"
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List domains

GET /api/admin/domains

Lists every domain on the server, active or not, with its certificate status and storage provider override.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is array of Domain.

{
  "success": true,
  "data": [
    {
      "id": "c7e2a1d4-5b6f-4a39-8e10-2f3d4c5b6a71",
      "hostname": "files.example.com",
      "is_primary": true,
      "is_active": true,
      "is_verified": true,
      "verified_at": "2026-09-14T08:30:00Z",
      "last_verified_at": "2026-10-03T06:00:00Z",
      "cert_name": "files.example.com",
      "cert_mode": "letsencrypt",
      "acme_email": "admin@example.com",
      "acme_last_attempt_at": "2026-09-30T02:10:00Z",
      "acme_last_success_at": "2026-09-30T02:10:00Z",
      "acme_cert_expires_at": "2026-12-29T00:00:00Z",
      "hsts_enabled": true,
      "created_at": "2026-09-14T08:20:00Z",
      "updated_at": "2026-09-30T02:10:00Z",
      "cert_status": {
        "hostname": "files.example.com",
        "cert_name": "files.example.com",
        "cert_path": "",
        "key_path": "",
        "loaded": true,
        "expires_at": "2026-12-29T00:00:00Z",
        "not_after_unix": 1798531200,
        "acme_email": "admin@example.com",
        "acme_cert_expires_at": "2026-12-29T00:00:00Z",
        "acme_last_success_at": "2026-09-30T02:10:00Z",
        "acme_last_attempt_at": "2026-09-30T02:10:00Z",
        "acme_renewal_window": "2026-11-29T00:00:00Z",
        "auto_renew": true
      }
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get the server’s public IP address

GET /api/admin/domains/public-ip

Looks up the server’s public IPv4 address, the address a domain’s DNS A record should point to. The lookup asks Cloudflare (1.1.1.1) and waits up to 5 seconds. If it fails, ipv4 is empty.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is PublicIp.

{
  "success": true,
  "data": {
    "ipv4": "203.0.113.10"
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a domain’s certificate status

GET /api/admin/domains/{id}/cert-status

Returns the certificate a domain serves, when it expires and, for Let’s Encrypt, the latest issuance attempt. For Let’s Encrypt, the server reads the current certificate and saves its expiry date if it changed.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Domain ID.

Response 200

data is DomainCertStatus.

{
  "success": true,
  "data": {
    "hostname": "files.example.com",
    "cert_name": "files.example.com",
    "cert_path": "",
    "key_path": "",
    "loaded": true,
    "status": "valid",
    "issuer": "R11",
    "dns_names": [
      "files.example.com"
    ],
    "not_after_unix": 1798531200,
    "expires_at": "2026-12-29T00:00:00Z",
    "acme_email": "admin@example.com",
    "acme_cert_expires_at": "2026-12-29T00:00:00Z",
    "acme_last_success_at": "2026-09-30T02:10:00Z",
    "acme_last_attempt_at": "2026-09-30T02:10:00Z",
    "acme_renewal_window": "2026-11-29T00:00:00Z",
    "auto_renew": true
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such item.	“Domain not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a domain’s settings

GET /api/admin/domains/{id}/settings

Returns the settings a domain overrides. A null field means the domain uses the server-wide setting. A domain with no settings of its own returns every field unset, and so does an unknown domain ID.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Domain ID.

Response 200

data is DomainSettings.

{
  "success": true,
  "data": {
    "domain_id": "c7e2a1d4-5b6f-4a39-8e10-2f3d4c5b6a71",
    "storage_provider": null,
    "max_upload_size_gb": 50,
    "link_expiry_days": 14,
    "max_link_lifetime_days": null,
    "link_format_template": null,
    "blocked_file_extensions": [],
    "display_name": "Example Legal",
    "has_logo": true,
    "logo_not_email_safe": false,
    "has_favicon": false,
    "has_background": false,
    "accent_color": "#0f766e",
    "email_invite_subject": null,
    "email_invite_title": null,
    "email_invite_body": null,
    "email_alert_subject": null,
    "email_alert_title": null,
    "email_alert_body": null,
    "email_footer": null,
    "disable_zip_browser": null,
    "sanitize_windows_filenames": null,
    "link_not_found_behavior": null,
    "link_not_found_redirect_url": null
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List private link networks

GET /api/admin/private-allowlists

Lists the networks allowed to open private links, server-wide lists first, up to 500. With domain_id, returns the server-wide lists and that domain’s lists.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`domain_id`	query	string	Only server-wide lists and the lists of this domain.

Response 200

data is array of PrivateAllowlist.

{
  "success": true,
  "data": [
    {
      "id": "5e9b0c12-7a3d-4f8e-b1c2-6d4e8f0a2b37",
      "name": "Office network",
      "description": "HQ and VPN",
      "cidr_ranges": [
        "203.0.113.0/24",
        "10.8.0.0/16"
      ],
      "is_active": true,
      "is_global": true,
      "created_at": "2026-09-15T09:00:00Z",
      "updated_at": "2026-09-15T09:00:00Z"
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a private link network list

GET /api/admin/private-allowlists/{id}

Returns one list of networks allowed to open private links.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	List ID.

Response 200

data is PrivateAllowlist.

{
  "success": true,
  "data": {
    "id": "5e9b0c12-7a3d-4f8e-b1c2-6d4e8f0a2b37",
    "name": "Office network",
    "description": "HQ and VPN",
    "cidr_ranges": [
      "203.0.113.0/24",
      "10.8.0.0/16"
    ],
    "is_active": true,
    "is_global": true,
    "created_at": "2026-09-15T09:00:00Z",
    "updated_at": "2026-09-15T09:00:00Z"
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such item.	“Allowlist not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List storage providers

GET /api/admin/storage-providers

Lists every storage provider with its usage and, for local storage, disk space and health. Access keys and secret keys are never returned. Local storage that was out of service and is healthy again goes back into service.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is array of StorageProvider.

{
  "success": true,
  "data": [
    {
      "id": "storage_default",
      "name": "Default local storage",
      "provider_type": "local",
      "base_path": "/app/storage",
      "is_active": true,
      "direct_upload_enabled": false,
      "total_bytes": 1000204886016,
      "used_by_dew": 52613349376,
      "free_bytes": 812345671680,
      "file_count": 1843,
      "created_at": "2026-09-14T08:00:00Z",
      "is_global_default": true,
      "domain_override_count": 0,
      "active_session_count": 0,
      "health_status": "ok",
      "is_registered": true
    },
    {
      "id": "b4d7e2f1-9a8c-4b3e-a6d5-1c2f3e4d5a6b",
      "name": "Cloudflare R2",
      "provider_type": "cloudflare-r2",
      "base_path": null,
      "endpoint": "https://0123456789abcdef.r2.cloudflarestorage.com",
      "region": "auto",
      "bucket": "dew-files",
      "path_style": true,
      "is_active": true,
      "direct_upload_enabled": true,
      "total_bytes": -1,
      "used_by_dew": 2147483648,
      "free_bytes": -1,
      "file_count": 120,
      "created_at": "2026-09-20T12:00:00Z",
      "is_global_default": false,
      "domain_override_count": 1,
      "active_session_count": 0,
      "is_registered": true
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a storage provider

GET /api/admin/storage-providers/{id}

Returns one storage provider with its usage and, for local storage, disk space and health. Access keys and secret keys are never returned.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Storage provider ID.

Response 200

data is StorageProvider.

{
  "success": true,
  "data": {
    "id": "b4d7e2f1-9a8c-4b3e-a6d5-1c2f3e4d5a6b",
    "name": "Cloudflare R2",
    "provider_type": "cloudflare-r2",
    "base_path": null,
    "endpoint": "https://0123456789abcdef.r2.cloudflarestorage.com",
    "region": "auto",
    "bucket": "dew-files",
    "path_style": true,
    "is_active": true,
    "direct_upload_enabled": true,
    "total_bytes": -1,
    "used_by_dew": 2147483648,
    "free_bytes": -1,
    "file_count": 120,
    "created_at": "2026-09-20T12:00:00Z",
    "is_global_default": false,
    "domain_override_count": 1,
    "active_session_count": 0,
    "is_registered": true
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such item.	“Storage provider not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List storage folders

GET /api/admin/storage-providers/mount-targets

Lists the folders the server can use for local storage: the built-in /app/storage and any folders mounted under /mnt/dew.

Permission: Settings: View (settings:read)
Service account tokens only, without Dew-Act-As.

Response 200

data is StorageMountTargets.

{
  "success": true,
  "data": {
    "default_path": "/app/storage",
    "extra_mount_prefix": "/mnt/dew",
    "targets": [
      {
        "path": "/app/storage",
        "fs_type": "bind",
        "is_bind": true,
        "writable": true,
        "is_system": true
      },
      {
        "path": "/mnt/dew/archive",
        "fs_type": "ext4",
        "is_bind": true,
        "writable": true,
        "is_system": false
      }
    ]
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or admin access isn’t allowed from the caller’s network.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get single sign-on status

GET /api/admin/sso/status

Returns whether single sign-on is turned on, whether SAML can be used and how many connections exist.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Response 200

data is SsoStatus.

{
  "success": true,
  "data": {
    "sso_enabled": true,
    "oidc_available": true,
    "saml_available": true,
    "saml_error": "",
    "connection_count": 1
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List single sign-on connections

GET /api/admin/sso/connections

Lists the single sign-on connections with the URLs to register at the identity provider. Client secrets and SCIM tokens are never returned.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Response 200

data is array of SsoConnection.

{
  "success": true,
  "data": [
    {
      "id": "e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "name": "Microsoft Entra ID",
      "provider_type": "saml",
      "provider": "entra",
      "client_secret_set": false,
      "saml_metadata_url": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/federationmetadata/2007-06/federationmetadata.xml",
      "saml_idp_sso_url": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/saml2",
      "saml_idp_entity_id": "https://sts.windows.net/00000000-0000-0000-0000-000000000000/",
      "saml_idp_cert_count": 1,
      "saml_idp_cert_expires_at": "2029-05-11T12:00:00Z",
      "saml_certificates": [
        {
          "expires_at": "2029-05-11T12:00:00Z",
          "additional": false
        }
      ],
      "saml_attr_email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "email_domains": [
        "example.com"
      ],
      "is_active": true,
      "allow_user_creation": true,
      "scim_enabled": true,
      "scim_bearer_token_set": true,
      "enforce_mode": "optional",
      "created_at": "2026-09-16T10:00:00Z",
      "updated_at": "2026-09-22T14:30:00Z",
      "sp_acs_url": "https://files.example.com/api/sso/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/acs",
      "sp_entity_id": "https://files.example.com/saml/sp/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "sp_metadata_url": "https://files.example.com/api/sso/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/sp-metadata",
      "scim_base_url": "https://files.example.com/scim/v2"
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a single sign-on connection

GET /api/admin/sso/connections/{id}

Returns one single sign-on connection with the URLs to register at the identity provider. Client secrets and SCIM tokens are never returned.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Single sign-on connection ID.

Response 200

data is SsoConnection.

{
  "success": true,
  "data": {
    "id": "e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
    "name": "Microsoft Entra ID",
    "provider_type": "saml",
    "provider": "entra",
    "client_secret_set": false,
    "saml_metadata_url": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/federationmetadata/2007-06/federationmetadata.xml",
    "saml_idp_sso_url": "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/saml2",
    "saml_idp_entity_id": "https://sts.windows.net/00000000-0000-0000-0000-000000000000/",
    "saml_idp_cert_count": 1,
    "saml_idp_cert_expires_at": "2029-05-11T12:00:00Z",
    "saml_certificates": [
      {
        "expires_at": "2029-05-11T12:00:00Z",
        "additional": false
      }
    ],
    "saml_attr_email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "email_domains": [
      "example.com"
    ],
    "is_active": true,
    "allow_user_creation": true,
    "scim_enabled": true,
    "scim_bearer_token_set": true,
    "enforce_mode": "optional",
    "created_at": "2026-09-16T10:00:00Z",
    "updated_at": "2026-09-22T14:30:00Z",
    "sp_acs_url": "https://files.example.com/api/sso/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/acs",
    "sp_entity_id": "https://files.example.com/saml/sp/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
    "sp_metadata_url": "https://files.example.com/api/sso/e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/sp-metadata",
    "scim_base_url": "https://files.example.com/scim/v2"
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
404	No such item.	“SSO connection not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Preview deleting a single sign-on connection

GET /api/admin/sso/connections/{id}/delete-impact

Counts the users who sign in through this connection and would be affected if it were deleted.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Single sign-on connection ID.

Response 200

data is SsoConnectionDeleteImpact.

{
  "success": true,
  "data": {
    "connection_id": "e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
    "attached_user_count": 42,
    "active_user_count": 39,
    "inactive_user_count": 3
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
404	No such item.	“SSO connection not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Preview requiring single sign-on

GET /api/admin/sso/connections/{id}/enforcement-impact

Counts the users who would no longer be able to sign in with a password if this connection’s enforce_mode were set to required.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	Single sign-on connection ID.

Response 200

data is SsoEnforcementImpact.

{
  "success": true,
  "data": {
    "affected_user_count": 12
  }
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
404	No such item.	“SSO connection not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List single sign-on events

GET /api/admin/sso/events

Lists recent single sign-on and SCIM events, newest first: sign-ins, refused sign-ins with the reason, users created or linked, and SCIM changes.

Permission: Settings: View (settings:read)
Plan: Pro
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`connection_id`	query	string	Only events of this connection.
`event_type`	query	string: `login`, `login_failed`, `user_provisioned`, `user_linked`, `scim_provision`, `scim_deprovision`, `scim_group_update`	Only events of this type.
`limit`	query	integer	Most events to return. A value outside 1 to 500 is ignored and 100 are returned. Default `100`. Minimum 1. Maximum 500.

Response 200

data is array of SsoEvent.

{
  "success": true,
  "data": [
    {
      "id": 1042,
      "connection_id": "e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "event_type": "login_failed",
      "user_email": "bob@example.com",
      "external_id": "bob@example.com",
      "details": {
        "reason": "no_access_for_new_account"
      },
      "created_at": "2026-10-03T09:14:22Z"
    },
    {
      "id": 1041,
      "connection_id": "e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "event_type": "login",
      "user_email": "anna@example.com",
      "external_id": "anna@example.com",
      "details": {
        "action": "login_success",
        "user_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091"
      },
      "created_at": "2026-10-03T09:10:05Z"
    }
  ]
}

Errors

Status	When	Example message
400	The request sent a `Dew-Act-As` header. Admin actions can’t act as a user.	“Dew-Act-As can’t be used for admin actions.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, admin access isn’t allowed from the caller’s network, or the license doesn’t include this feature.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.” “This feature is available on the Pro and Enterprise plans.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.