Démarrer

Authentification

Chaque requête porte une clé d’API. Une clé appartient à votre compte, porte des droits et peut expirer ; vous la créez et la révoquez vous-même.

Obtenir une clé

Les clés se créent dans Mes clés, une fois l’accès ouvert pour votre compte (pendant la bêta, sur demande). À la création, vous choisissez un nom, les droits de la clé (parmi ceux de votre compte) et sa validité : 30 jours, 90 jours, 1 an (par défaut) ou sans expiration. Par défaut, un compte peut avoir 5 clés actives à la fois.

Une clé commence par ri_live_, suivi de 38 lettres et chiffres. Elle ne s’affiche qu’une fois : copiez-la dans votre gestionnaire de secrets. Elle porte une somme de contrôle : une clé tronquée ou mal copiée est refusée aussitôt (invalid_api_key).

Envoyer la clé

Passez la clé dans l’en-tête Authorization: Bearer ri_live_…. L’en-tête X-API-Key: ri_live_… est aussi accepté.

Jamais dans l’adresse : une requête qui porte api_key, apikey, key, token ou access_token dans sa chaîne de requête, ou une valeur commençant par ri_live_, est refusée (400 api_key_in_url). Les adresses finissent dans les journaux : une clé passée ainsi doit être considérée comme exposée, remplacez-la.

L’API n’envoie pas d’en-têtes CORS : un navigateur refuse d’en lire les réponses depuis un autre site. Appelez-la depuis votre serveur, jamais depuis du code envoyé à un navigateur.

Les droits

Droit	Donne accès à
`listings:read`	Recherche d’annonces, fiche et historique d’un bien (`/v1/listings`, `/v1/listings/{id}`, `/v1/listings/{id}/history`).
`valuations:read`	Audit de prix complet (`/v1/listings/{id}/valuation`), champ `audit` des annonces, tri `delta` et filtre `labels`.
`market:read`	Marché d’une commune et ventes DVF (`/v1/market/…`).
`changes:read`	Flux des changements (`/v1/changes`).

GET /v1/me n’exige aucun droit particulier. Une clé n’a que les droits qu’elle a reçus et que votre compte détient encore : si un droit est retiré au compte, ses clés le perdent aussi. Un point d’entrée appelé sans son droit répond 403 insufficient_scope, avec le droit exigé dans details.required_scope.

Sans valuations:read, les annonces n’ont pas de champ audit, et le flux des changements ne vous envoie pas les modifications qui ne touchent que l’audit.

Vérifier une clé

GET /v1/me décrit la clé utilisée (nom, début de la clé, droits, expiration), le plan du compte, ses limites et la consommation du jour. C’est l’appel à faire pour contrôler une clé au démarrage de votre service. Voir la référence.

Expiration et rotation

Une clé expirée répond 401 expired_api_key. Surveillez key.expires_at de /v1/me et remplacez la clé avant l’échéance, sans interruption :

créez une nouvelle clé dans Mes clés ;
déployez-la sur vos serveurs ;
vérifiez avec /v1/me que key.prefix est bien celui de la nouvelle clé ;
révoquez l’ancienne.

Pendant la rotation, les deux clés partagent les limites du compte, comme toutes ses clés.

Révocation

Une clé se révoque en un clic dans Mes clés. La révocation prend effet en 15 secondes au plus ; la clé répond ensuite 401 revoked_api_key. Révoquez sans attendre une clé exposée.

D’autres refus portent sur le compte, toutes clés confondues : accès à l’API coupé (403 api_access_disabled), compte désactivé (403 account_disabled), compte ou adresse IP bloqués (403 account_blocked, ip_blocked). Écrivez-nous en citant le request_id de la réponse.

Trop de clés invalides

Une adresse IP qui présente trop de clés mal formées ou inconnues en peu de temps est mise à l’écart pendant 15 minutes : toutes ses requêtes reçoivent alors 429 too_many_auth_failures, même avec une bonne clé, et l’en-tête Retry-After donne l’attente restante. Ne relancez jamais en boucle une requête refusée en 401.