FastDDNS Client API

Aperçu

L’API client FastDDNS permet à tout appareil compatible HTTP — routeurs, caméras IP, scripts ou logiciels dédiés de mise à jour — de maintenir votre hostname DNS associé à votre adresse IP actuelle. L’API repose sur un format simple de requête GET : votre client envoie des identifiants et un hostname, puis le serveur répond par un court code d’état indiquant le résultat.

Le serveur détecte automatiquement l’adresse IP publique du client à partir de la connexion entrante. Aucun paramètre supplémentaire n’est nécessaire pour spécifier votre IP.

Authentification

L’API prend en charge deux méthodes d’authentification. Les deux sont acceptées de la même manière : choisissez celle qui est la plus facile à configurer sur votre appareil ou votre router.

Méthode 1 — Authentification HTTP Basic Auth (intégrée à l’URL)

Les identifiants sont intégrés à l’URL en utilisant le format standard user:password@host. Ce format est largement pris en charge par les routeurs, les caméras et les bibliothèques clientes HTTP. Utilisez la clé client de mise à jour depuis votre tableau de bord comme mot de passe.

Méthode 2 — Paramètres de chaîne de requête

Les identifiants sont transmis sous forme de simples paramètres de requête à côté de hostname. Cette méthode est utile pour les appareils et les firmware qui ne peuvent pas configurer les en-têtes HTTP Basic Auth, mais qui acceptent une chaîne d’URL entièrement personnalisée.

Exemple d’authentification par chaîne de requête :

Effectuer la mise à jour

Envoyez une seule requête GET pour mettre à jour l’adresse IP d’un hostname enregistré sur votre compte. Chaque requête met à jour un hostname à la fois.

Endpoint

Format URL — Méthode 1 : authentification HTTP Basic

Format URL — Méthode 2 : chaîne de requête

Paramètres de requête

Exemples de requêtes

Méthode 1 — authentification HTTP Basic via HTTPS :

Méthode 2 — Chaîne de requête via HTTPS :

Utilisation du HTTP simple (tests / réseaux de confiance uniquement) :

Codes de retour

Toutes les réponses à la mise à jour renvoient le statut HTTP 200 OK avec un corps en texte brut. Votre client doit analyser ce corps de texte pour déterminer le résultat réel de la mise à jour.

Résumé de la réponse

Obtenir l’IP du client

FastDDNS fournit un point de terminaison utilitaire simple qui renvoie l’adresse IP publique telle qu’elle est vue par le serveur. Cet endpoint est utile pour le débogage, pour vérifier l’IP depuis laquelle votre appareil envoie ses requêtes ou pour l’utiliser dans des scripts personnalisés avant d’appeler l’endpoint de mise à jour.

Endpoint

Réponse

Renvoie HTTP 200 OK avec l’adresse IP publique détectée, sous forme de texte brut dans le corps de la réponse.

# Example response body
203.0.113.45RESPONSE

Exemples de requêtes

Avec curl :

curl https://client.fastddns.net/dyndns/getipSHELL

Exemples de code

Shell / cURL

# Recommended: let curl build the Authorization header (-u), so the
# credentials never appear in the URL.
HOSTNAME="myhome.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}"
# Legacy form, for devices that can only be given one URL field:
curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}"
# Check what IP the server sees from your device
curl -s "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "YOUR_UPDATE_USERNAME"
USER_PASS = "YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
resp = requests.get(
    "https://client.fastddns.net/",
    auth=(USER_NAME, USER_PASS),
    params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
#     "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
    print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
    print(f"No change needed: {body}")
elif body == "badauth":
    print("Authentication failed. Check credentials.")
elif body == "nohost":
    print("Hostname not found.")
elif body == "911":
    print("Server error. Try again later.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'YOUR_UPDATE_USERNAME';
$user_pass = 'YOUR_UPDATE_PASSWORD';
// Recommended: Basic Auth in a request header, so the password is not
// part of the URL and cannot leak through logs or error messages.
$url = "https://client.fastddns.net/?hostname=" . urlencode($hostname);
$auth = 'Basic ' . base64_encode($user_name . ':' . $user_pass);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
//      . "&user_name=" . urlencode($user_name)
//      . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => [
    'timeout' => 10,
    'header'  => "Authorization: {$auth}\r\n",
]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
    case str_starts_with($body, 'good'):
        echo "Updated: {$body}\n"; break;
    case str_starts_with($body, 'nochg'):
        echo "No change: {$body}\n"; break;
    case $body === 'badauth':
        echo "Auth failed. Check hostname credentials.\n"; break;
    case $body === 'nohost':
        echo "Hostname not found.\n"; break;
    case $body === '911':
        echo "Server error, retry later.\n"; break;
}PHP

Bash (Cron / script de router)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
  good*)   echo "[OK] $RESULT" ;;
  nochg*)  echo "[OK] $RESULT" ;;
  badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
  nohost)  echo "[ERR] Hostname not found"; exit 1 ;;
  911)     echo "[ERR] Server error, retry later"; exit 1 ;;
  *)       echo "[WARN] Unknown response: $RESULT" ;;
esacBASH

Dépannage

Je reçois badauth

Le user_name ou user_pass fournis ne correspondent pas aux identifiants attribués à ce hostname. Chaque hostname possède ses propres identifiants — vous les trouverez dans votre tableau de bord, sous Hostnames → Details. Notez que ces identifiants sont spécifiques au hostname et ne peuvent pas être utilisés pour se connecter au portail de gestion FastDDNS. Si vous avez récemment réinitialisé les identifiants, mettez à jour tous les appareils utilisant ce hostname.

Je reçois nohost

Le hostname indiqué dans le paramètre hostname n’existe pas ou n’appartient pas au compte identifié par les identifiants fournis. Vérifiez que le hostname ne contient pas de faute de frappe, confirmez qu’il figure dans votre tableau de bord et vérifiez que le user_name et le user_pass correspondent à ce hostname précis.

Le serveur détecte la mauvaise adresse IP

Le serveur utilise l’IP source de la connexion TCP. Si votre appareil est derrière un routeur NAT, l’IP publique du routeur sera détectée — ce qui est généralement le comportement souhaité. Si vous utilisez un VPN ou un proxy, le serveur verra l’IP de sortie du VPN ou du proxy. Utilisez le getip endpoint pour vérifier quelle IP le serveur voit depuis votre appareil.

Je reçois 911

Cela indique un problème temporaire côté serveur. Attendez au moins 5 minutes avant de réessayer. N’envoyez pas de requêtes en boucle rapidement : cela peut déclencher une limitation du débit. Consultez la page d’état de FastDDNS pour connaître les incidents en cours.

À quelle fréquence dois-je interroger le point de terminaison de mise à jour ?

Nous recommandons de vérifier les changements d’IP toutes les 5 minutes. Lorsque votre IP n’a pas changé, le serveur renvoie nochg, ce qui ne déclenche aucune action et consomme peu de ressources. Il est déconseillé d’interroger le point de terminaison plus d’une fois par minute, car cela peut entraîner une limitation du débit.