api-access

Manage Mullvad API access methods

The mullvad api-access command manages access methods for connecting to the Mullvad API. Access methods are used when direct connections fail, such as when using the VPN from censored networks.

Overview

Access methods allow the Mullvad daemon to reach the API via:

• Direct connection (default)
• Mullvad bridge servers
• Custom SOCKS5 proxies
• Custom Shadowsocks proxies

If the daemon cannot connect directly to the API, it automatically tries configured access methods until one succeeds.

Usage

mullvad api-access <SUBCOMMAND>

Subcommands

list

List all configured API access methods.

mullvad api-access list

Example output:

Current: Direct

Built-in:
  1. Direct (active)
  2. Mullvad Bridges

Custom:
  3. My SOCKS5 Proxy
  4. Shadowsocks Proxy

add

Add a custom API access method.

mullvad api-access add <TYPE> <NAME> <CONFIG>

Supported types:

• socks5 - SOCKS5 proxy
• shadowsocks - Shadowsocks proxy

remove

Remove a custom API access method by name or index.

mullvad api-access remove <NAME_OR_INDEX>

set

Set the active API access method.

mullvad api-access set <NAME_OR_INDEX>

test

Test an API access method.

mullvad api-access test <NAME_OR_INDEX>

Examples

List access methods

mullvad api-access list

Add SOCKS5 proxy

mullvad api-access add socks5 "My Proxy" \
  --server 192.168.1.100:1080 \
  --username myuser \
  --password mypass

Add Shadowsocks proxy

mullvad api-access add shadowsocks "SS Proxy" \
  --server 192.168.1.100:8388 \
  --password mypassword \
  --cipher aes-256-gcm

Set active method

mullvad api-access set 2

Sets the access method at index 2 as active.

Test access method

mullvad api-access test "My Proxy"

Tests if the specified proxy can reach the Mullvad API.

Remove custom method

mullvad api-access remove "My Proxy"

Built-in access methods

Direct

Connects directly to the Mullvad API over HTTPS. This is the default and fastest method when available.

Mullvad Bridges

Connects via Mullvad’s bridge servers using Shadowsocks. Automatically configured and maintained by Mullvad. Useful when direct connections are blocked.

Custom access methods

You can add custom proxies when:

• Operating in networks with strict firewall rules
• Behind corporate proxies
• In regions with heavy censorship
• You have your own proxy infrastructure

Custom access methods are used to reach the Mullvad API, not for VPN traffic. VPN traffic uses the configured tunnel protocol.

Automatic failover

The daemon automatically:

1. Tries the currently active access method
2. If that fails, tries other configured methods in order
3. Switches to the first successful method
4. Retries periodically if all methods fail

What requires API access

• Account login and logout
• Fetching relay list
• WireGuard key rotation
• Device management
• Voucher redemption
• Account information queries

Once connected to the VPN, API calls go through the tunnel. Access methods are primarily used before connection or when disconnected.

Exit status

• 0 - Success
• 1 - Daemon error, invalid configuration, or connection failure

Related commands

• anti-censorship - Configure tunnel obfuscation
• status - Check connection status