Skip to main content


dynDNS offers a dyndns endpoint compatible with protocol v2 and v3 of

The protocol has been expanded to support and overcome Browser modifications like the prohibition to embed authentication in URLs.

Here we show the full protocol accepted by

Basic Syntax

All requests must be sent to the endpoint using HTTP protocol and Basic HTTP Authentication.

The basic request is the following:


  • HOSTNAME is the full hostname to update (ie.

IP Update

After receiving this request, gets the public IP from where the request originates and sets the Hostname. In 30 seconds, the hostname starts to respond with the IP of the connection.

Response codes

The response for the request is one word followed by optional additional information.

ResponseAdditional DataExampleMeaning
okIP Receivedok IP has been accepted and the hostname has been updated.
nochgIP Receivednochg IP is already assigned to the Hostname. The client must send updates only when the IP changes. Sending duplicate updates is considered abusive behavior.
badauthbadauthThe server can not authenticate the request for the hostname using the user and password sent.
!donor!donorThe action requested is reserved to active account. The account can be expired.
abuseabuseThe account has been suspended due to abusive behavior
911911The server is experiencing a major issue. The client must wait 10 minutes before sending more updates.


The request can include more parameters, all in the query string. All parameters that can be included in the request are the following. All parameters are optional, only the hostname is required.

hostnamethe full hostnamehostname = myhost.ns0.itThe hostname to update. This parameter must be present in every request
myipany public IPmyip= IP to use to update the hostname. If not present in the request, the server will use the IP address from which the request originates
wildcardON or OFFwildcard=ONActivates/Deactivates all fourth-level domains pointing to the main hostname. For example
usernamevalid usernameusername=fredThe username to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter password
passwordvalid passwordpassword=1234The password to authenticate the request. Used instead of the ‘Authorization’ HTTP header with the parameter username
keyvalid hostkeykey=xfgtThe key authenticating the request. Used instead of the ‘Authorization’ HTTP header and the username and password parameters
mxdeprecatedUsed in the past to assign a mail server for the hostname
systemdeprecatedUsed in the past to distinguish between dynamic and static domains


The update protocol is based on HTTP and can be easily tested using a web browser. In the following examples, you should insert the values from your account.

Update hostname using the current connection IP:

The hostname will point to the IP of the connection from where the request is sent.

Update hostname with explicit IP to use:

The hostname will point to the IP sent. accepts only public IPs. Private IPs like 192.168.x.x or 10.x.x.x are not assigned to hostnames.

Embed authentication with user and password

You can pass username and password as query string parameters without using an ‘Authorization’ Header

Embed authentication with key

You can pass HOSTKEY as query string parameters without using an ‘Authorization’ Header

Technical Notes

  1. All interactions with the update platform are made via HTTP/HTTPS protocol using exclusively the GET method.
  2. The server is available at the address:, on port 80 for HTTP and on port 443 for the HTTPS.
  3. Parameters are sent to the update platform as name/value pairs as part of the HTTP query string. Please note that all parameters are optional while only the hostname is mandatory.
  4. Authentication is required for all requests. platform accepts different authentications method to update hostnames. (HTTP basic auth or username and password as parameters)
  5. The general authentication method uses Basic HTTP Authentication. This method, commonly used by browsers, requires a Header, containing user and password, encoded in base64. For more information consult
  6. An alternative authentication method requires the inclusion of USERNAME and PASSWORD parameters in the query string.
  7. After every request, the client receives a RESPONSE from the update platform in a one-word code followed by any additional information. The client reading the RESPONSE can understand if the update requested has been successful.
  8. The updating script must send updates ONLY when the IP of the connection changes, otherwise it is considered abusive behavior. The IP of the connection can be checked by sending an unauthenticated GET to the endpoint.

RAW HTTP Request Example

The generic request to the update platform, using Basic HTTP Authentication:

GET /nic/update?hostname=[MY-HOSTNAME] HTTP/1.1

Client structure example

A generic client should implement the following structure:

  1. Get the current connection IP from
  2. if the current IP is different from the locally saved IP
    • Send the update to
    • Save the current IP in local storage
  3. Sleep 5 minutes
  4. jump to 1

Staff ufficiale del sito, impegnati a fornire informazioni e indicazioni agli utenti dall'Aprile del 2001