Start with the trust boundary
List your production API domains, development endpoints and any enterprise certificate authority. Do not include entire parent domains merely because one test subdomain needs an exception. A broad inherited exception can silently apply to a future service.
A conservative starting point is:
<network-security-config>
<base-config cleartextTrafficPermitted="false">
<trust-anchors>
<certificates src="system" />
</trust-anchors>
</base-config>
</network-security-config>
Reference the resource with android:networkSecurityConfig on <application>. This example describes trust policy; it does not configure your API URL or request permissions.
Separate development certificates
A development proxy may require a user-installed or bundled certificate. Use the platform's debug-only trust mechanism when appropriate, rather than adding development trust to the release base configuration. Verify that android:debuggable is false in the published artifact.
The official configuration reference explains inheritance, domain matching and debug overrides. Read the effective rules from most specific to least specific; nested configurations can inherit attributes you did not repeat explicitly.
Review these decisions explicitly
| Setting | Evidence to retain |
|---|---|
includeSubdomains |
Inventory of subdomains that should inherit the rule |
| User certificate trust | A documented enterprise or debugging requirement |
| Bundled CA | Owner, rotation process and supported lifetime |
| Cleartext exception | Exact endpoint and removal condition |
| Pin set | Valid primary and backup keys plus rotation tests |
A configuration is not safer because it contains more XML. An unnecessary pin set can create operational failure, while a broad user-CA allowance can weaken a release client's assumptions.
Check all clients, not one request
Exercise authentication, image loading, background work, WebViews and SDK traffic. Libraries using custom native stacks may have their own trust configuration. If one request succeeds and another fails, compare their transport implementations before expanding trust globally.
Inspect source and packaged output
APKLint's Network Security Config Checker can review the intended XML, while APK inspection helps establish which resource and manifest reference shipped. Neither substitutes for checking the live certificate chain and testing device/version combinations. Keep configuration changes in code review with a reason for every exception.
Sources and further reading
Reference review: 22 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
