auth0_connection (sms strategy): expose options.use_phone_provider to manage the per-connection Unified Phone Experience flag

[vr]

Checklist

• I agree to the terms within the Auth0 Code of Conduct.

Describe the problem you'd like to have solved

When migrating an existing tenant from a legacy SMS gateway to the Unified Phone Experience (UPE) for Passwordless via the custom-phone-provider Action, the dashboard exposes a toggle:

Authentication > Passwordless > SMS > Use Tenant-Level Messaging Provider

Enabling this toggle writes a hidden field options.use_phone_provider: true (the string "unified" is also accepted) on the SMS connection. Without it, Passwordless requests on legacy tenants continue to be routed through the connection's provider: "sms_gateway" settings, bypassing the configured tenant phone provider / Action — even when:

• auth0_phone_provider is set to name = "custom" and disabled = false
• A custom-phone-provider (v1) Action is deployed and bound via auth0_trigger_actions
• auth0_tenant.flags.phone_consolidated_experience = true

This field is currently not exposed by the provider (any version up to and including v1.44.0) nor by the underlying auth0/go-auth0 SDK, so it's impossible to flip this toggle from Terraform. Tenants created after UPE became default appear to route Passwordless via the tenant phone provider without this flag, which is why the gap is invisible until you migrate an older tenant.

Repro on a tenant created before UPE became default:

resource "auth0_connection" "sms" {
  strategy = "sms"
  options {
    provider               = "sms_gateway"
    gateway_url            = "https://example.com/otp"
    gateway_authentication { ... }
    # no way to set use_phone_provider = true here
  }
}

`terraform apply` succeeds, the Action is bound, the tenant phone provider is `custom`, but Passwordless SMS keeps hitting the legacy gateway

### Describe the ideal solution

Add support for `options.use_phone_provider` (boolean) on `auth0_connection` when `strategy = "sms"`:

```hcl
resource "auth0_connection" "sms" {
  strategy = "sms"
  options {
    use_phone_provider = true
    # ...
  }
}

It should map to the options.use_phone_provider field returned by GET /api/v2/connections/{id} and survive PATCH round-trips.

Alternatives and current workarounds

1. Direct PATCH /connections/{id} via Management API. Works (HTTP 200), but PATCH on options is a full replace, not a merge — sending {"options":{"use_phone_provider":true}} wipes all other connection options (template, gateway settings, totp, brute_force_protection, etc.). The full options payload (including the write-only gateway_authentication.secret) must be re-sent each time. The dashboard itself fails on this with Payload validation error: 'Missing required property: secret' on property options.gateway_authentication because it doesn't know the masked secret.

2. null_resource + local-exec curl triggered on sha256(jsonencode(auth0_connection.sms.options)) to re-PATCH the flag after every Terraform-driven update of the connection. Works but fragile and bypasses the provider's drift detection.

3. Mastercard/restapi provider to manage just this field — adds a whole provider for a single attribute.

Additional context

• Provider versions tested: v1.43.0 and v1.44.0
• go-auth0 ConnectionOptionsSMS (current main): no UsePhoneProvider field
• Behavior observed on EU region tenants (*.eu.auth0.com)
• Related already-supported tenant flag: auth0_tenant.flags.phone_consolidated_experience (added in v1.41.0, Added support for managing UnifiedPhoneExperience #1495)
• Auth0 docs referencing the toggle: https://auth0.com/docs/customize/phone-messages/unified-phone/unified-phone-experience-passwordless

Adding this single attribute would close the last gap preventing a fully Terraform-managed migration to the Unified Phone Experience for Passwordless on legacy tenants.

[duedares-rvj]

Hello @vr 👋

Thank you for opening this with such detail.
I went on to try and reproduce this but haven't been able to see this on UI via network tab:

I clicked save and on the right is the network payload.

Can you share more about the hidden field that you are referring?

[duedares-rvj]

Hello again!
Gentle nudge in case you missed my earlier comment.

[vr]

Hi @duedares-rvj, thanks for looking into this — and apologies for the delayed reply.

The screenshot you shared looks like Authentication > Passwordless > SMS on a tenant that already routes through the Unified Phone Experience by default. If that's the case, the toggle I'm referring to probably isn't shown there because the legacy SMS-gateway path doesn't apply, which would explain why nothing extra appears in the network tab.

From what I've observed on our side, the toggle and the underlying field seem to only surface on tenants that meet roughly these conditions (this is my best reconstruction, not something I've seen documented):

1. The SMS Passwordless connection has options.provider = "sms_gateway" (i.e. a custom HTTP gateway was previously configured)
2. auth0_tenant.flags.phone_consolidated_experience = true
3. A tenant-level Phone Provider (Branding > Phone Provider) is set to custom with a custom-phone-provider Action bound

On such tenants, the toggle appeared for us under Branding > Phone Provider > Settings, and saving it seemed to issue a PATCH /api/v2/connections/{id} that adds options.use_phone_provider to the existing options object. I couldn't fully confirm the exact dashboard call path because of the dashboard error described below — most of my certainty comes from inspecting the resulting connection via the Management API.

Evidence from one of our EU tenants

GET /api/v2/connections/{sms_connection_id} after enabling the toggle returned something like this (values redacted/edited):

{
  "strategy": "sms",
  "name": "sms",
  "options": {
    "name": "sms",
    "from": "+1 234 567",
    "syntax": "liquid",
    "template": "...",
    "provider": "sms_gateway",
    "gateway_url": "https://<redacted>/otp-sendings",
    "gateway_authentication": {
      "method": "bearer",
      "subject": "Auth0",
      "audience": "MessageGateway",
      "secret": "<redacted>",
      "secret_base64_encoded": true
    },
    "totp": { "length": 6, "time_step": 300 },
    "brute_force_protection": true,
    "disable_signup": false,
    "forward_req_info": false,
    "use_phone_provider": true
  }
}

On a second tenant where the toggle was flipped via the dashboard, the field came back as "use_phone_provider": "unified" (string) instead of true (boolean). I haven't dug into what drives that difference. In both cases, PATCH /api/v2/connections/{id} accepted the value we sent (we tried both true and "unified"), and once the field was present, subsequent Passwordless SMS requests appeared to go through the custom-phone-provider Action rather than the sms_gateway defined in the same options object. Removing the field (by omitting it from a full-options PATCH) seemed to revert routing back to the legacy gateway, with no other config change on our side — though I haven't exhaustively tested every combination.

Indirect signal that the dashboard writes into this field

When we tried to flip the toggle from Authentication > Passwordless > SMS directly in the dashboard, it failed with:

Payload validation error: 'Missing required property: secret' on property options.gateway_authentication

Our interpretation is that the dashboard is PATCHing the full options object (including the masked gateway_authentication) plus the new flag, but doesn't have access to the write-only gateway_authentication.secret it just masked, so validation rejects the request. Doing the equivalent PATCH server-to-server with the real secret succeeded and persisted options.use_phone_provider. That's what led us to conclude that the toggle writes into options on the connection itself rather than going through a separate API — but I'd treat that as a strong hypothesis rather than a fact.

Field summary (as we observed it)

Field	Type	Where	Values we've seen
options.use_phone_provider	bool | string	auth0_connection (strategy sms)	true, "unified", or absent

Happy to share an anonymised full GET payload over a private channel if it would help — and equally happy to be corrected if any of the above doesn't match the intended behavior on the Auth0 side.