dingtalk-workspace-cli/docs/international-region-guide.md

International DingTalk (.io) Guide

This guide explains how to log in to the international DingTalk region and run DWS commands against *.dingtalk.io services.

Region behavior

• dws auth login --intl creates or refreshes an international login using the .io login, OAuth, and MCP services.
• Omitting --intl keeps the existing domestic .com behavior.
• --intl is a login option, not a global option for business commands. After login, commands such as contact, calendar, and doc derive the region from the selected Token/profile.
• Each new Token records its login region. Switching profiles therefore switches the official DingTalk gateway region automatically.
• --international is a compatibility alias. Prefer --intl in new scripts.

For the complete Chinese guide, see DWS 国际版（DingTalk .io）使用手册.

Check availability

dws auth login --help

The help output must include --intl and --international.

When validating a source checkout, build it first and use ./dws so an older binary on PATH is not invoked accidentally:

make build
./dws auth login --help

Log in

Browser login:

dws auth login --intl

Device flow for SSH, containers, and headless environments:

dws auth login --intl --device

User OAuth with custom application credentials:

dws auth login --intl \
  --client-id <APP_KEY> \
  --client-secret <APP_SECRET>

This mode still requires the user to complete OAuth authorization in a browser; it is not a userless client_credentials login. The application must be configured on the international developer platform with the required callback and permissions. Never commit an AppSecret to source control or include it in logs.

Verify the login

dws auth status --format json
dws profile list --format json
dws contact user get-self

The last command is a read-only smoke check. If the organization has not enabled CLI access, an organization administrator must enable it or approve the access request on the international developer platform.

Use domestic and international profiles together

# Domestic (.com)
dws auth login

# International (.io)
dws auth login --intl

# Find the stable profile selectors
dws profile list --format json

Persistently switch profiles:

dws profile switch <corpId>:<userId>

Toggle back to the previous profile:

dws profile switch -

Select a profile for one command without changing the default:

dws --profile <corpId>:<userId> contact user get-self

Do not add --intl to business commands. DWS routes official endpoints from the selected profile's Token region.

Isolated smoke testing

Use a separate configuration directory to avoid changing the normal ~/.dws login state:

DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth login --intl
DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws auth status --format json
DWS_CONFIG_DIR=/tmp/dws-intl-smoke ./dws contact user get-self

Use the same DWS_CONFIG_DIR for every command. Use ./dws for a source build and dws for an installed release.

Pre-release overrides (maintainers only)

Normal international users need only --intl; they should not set --pre-url or --mcp-url.

Maintainers can test the pre-release login/MCP pair with:

dws auth login --intl --pre-url https://pre-login.dingtalk.io

A corresponding pre-mcp.* URL is also accepted, and DWS derives the paired pre-login.* / pre-mcp.* bases. --mcp-url explicitly overrides the MCP base URL for that login.

Pre-release services may require internal network access or allowlisted accounts. --pre-url is intended primarily for the MCP-managed credential flow. Do not combine it with direct custom --client-id/--client-secret mode unless the pre-release API contract explicitly supports that combination.

Troubleshooting

The browser still opens a .com page

1. Run dws auth login --help and confirm --intl is present.
2. For a source checkout, use ./dws instead of an older installed binary.
3. Confirm the executed command is dws auth login --intl.

A business command appears to use the wrong region

Run dws profile list --format json, then switch with the exact <corpId>:<userId> selector or use the global --profile option. For a legacy Token created before region metadata existed, reauthorize it with dws auth login --intl for an international account or dws auth login for a domestic account.

Login succeeds but the command reports missing permission

This normally means the organization has not enabled CLI access or the application lacks a required permission. It does not by itself indicate a region-routing failure.

Should I edit ~/.dws/mcp_url manually?

No. Normal users should establish the login with dws auth login or dws auth login --intl. DWS then routes official endpoints from the selected Token/profile. Manual configuration is reserved for maintainers who explicitly control the target environment.

Command reference

Scenario	Command
Domestic browser login	dws auth login
International browser login	dws auth login --intl
International device login	dws auth login --intl --device
Check auth state	dws auth status --format json
List profiles	dws profile list --format json
Persistently switch profile	dws profile switch <corpId>:<userId>
Toggle to previous profile	dws profile switch -
Select a profile once	dws --profile <corpId>:<userId> <command>