Documentation OAuth — Ayeba Developers

Clés API — authentification

Les APIs REST /api/v1/* s’authentifient par clé, créée dans la console et rattachée à un projet. Le secret complet n’est affiché qu’une fois — seul son hash est conservé côté serveur.

curl "https://ayeba.app/api/v1/search?q=kinshasa" \
  -H "Authorization: Bearer ayb_live_…"

Chaque clé peut être limitée par portées (search, suggest, ayebi, radar, crawl, velocity), quota quotidien, référents et adresses IP autorisés. L’API doit aussi être activéedans la bibliothèque du projet. Les appels sont journalisés et visibles dans l’onglet Journaux de la console.

Ayeba Search API

GET /api/v1/search?q=…&limit=10 — recherche web sur l’index Ayeba. Réponse JSON :

{
  "query": "kinshasa",
  "total": 27,
  "results": [
    { "title": "…", "url": "https://…", "domain": "…", "description": "…" }
  ],
  "knowledge": null | { … }
}

limit : 1–50 (défaut 10). Portée requise : search.

Ayeba Suggest API Bêta

GET /api/v1/suggest?q=…&limit=8 — suggestions de recherche en temps réel (autocomplete). Réponse :

{ "query": "kin", "suggestions": ["kinshasa", "…"] }

limit : 1–10 (défaut 8). Portée requise : suggest.

Ayebi Encyclopedia API

GET /api/v1/ayebi?q=…&limit=10&category= — recherche dans l’encyclopédie congolaise Ayebi (corpus distinct de Wikipédia).

{
  "query": "kinshasa",
  "total": 4,
  "source": "ayebi",
  "results": [
    {
      "slug": "kinshasa",
      "title": "Kinshasa",
      "summary": "…",
      "category": "géographie",
      "url": "https://ayeba.app/ayebi/kinshasa",
      "stub": false
    }
  ]
}

Portée requise : ayebi. Paramètre optionnel category pour filtrer les fiches.

Ayeba Radar Performance API Bêta

GET /api/v1/radar?domain=example.com&days=28&dim=query — Search Analytics lecture seule pour un domaine Studio vérifié (clics, impressions, CTR, position, comparaison vs période précédente).

Portée : radar. Le domaine doit appartenir au propriétaire du projet Developers et être vérifié dans Studio.

Ayeba Crawl Status API

GET /api/v1/crawl/status?domain=example.com— statut d’indexation réel (pages indexées, file de crawl, couverture, échecs) pour un domaine Studio vérifié.

{
  "domain": "example.com",
  "status": "verified",
  "overview": {
    "indexedPages": 42,
    "submittedUrls": 50,
    "coveragePct": 84,
    "queuePending": 3,
    "queueFailed": 0
  },
  "coverage": { "totals": { … }, "recentIndexed": [ … ] }
}

Portée : crawl. Données issues de crawl_documents / crawl_queue — aucun mock.

Ayeba Velocity API Bêta

POST /api/v1/velocity— déclenche un audit Lighthouse réel via Google PageSpeed Insights pour une URL d’un domaine Studio vérifié.

curl -X POST "https://ayeba.app/api/v1/velocity" \
  -H "Authorization: Bearer ayb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","strategy":"mobile"}'

Corps JSON : domain (requis), url (optionnel), strategy (mobile|desktop). Portée : velocity. Réponse : scores lab, métriques, CrUX field data, historique.

Erreurs & quotas

401 — clé absente ou invalide.
403 — clé désactivée/révoquée, portée manquante, API non activée sur le projet, ou restriction référent/IP non satisfaite.
429 — quota quotidien de la clé dépassé.
400 — paramètre q manquant ou invalide.

Les quotas sont par clé et par jour (minuit UTC). Augmentez-les dans la console ou créez plusieurs clés par environnement (dev/prod).

Vue d’ensemble

Ayeba agit comme fournisseur d’identité. Après autorisation par l’utilisateur, votre application reçoit des jetons lui permettant de reconnaître de façon stable la même personne à travers vos services, sans gérer elle-même le mot de passe Ayeba.

Les identifiants de votre application (client_id, client_secret, redirect URIs) sont délivrés exclusivement dans la console OAuth après authentification. Ils ne sont pas publiés sur les pages marketing du site.

Découverte OpenID

Comme pour tout fournisseur OpenID Connect conforme, les endpoints publics sont décrits dans le document de découverte. Votre serveur doit lire ce document plutôt que de coder en dur des chemins susceptibles d’évoluer :

https://ayeba.app/.well-known/openid-configuration

Ce document expose notamment les adresses d’autorisation, d’échange de jetons et d’informations utilisateur, ainsi que les algorithmes de signature des id_token.

Flux authorization code

Le flux recommandé pour les applications serveur est le code d’autorisation ( response_type=code. L’utilisateur est redirigé vers Ayeba, s’authentifie et consent, puis revient sur votre redirect_uri avec un code à courte durée de vie.

L’échange du code contre des jetons s’effectue uniquement côté serveur, avec votre client_secret (ou PKCE pour les clients publics). Ne placez jamais le secret dans une application frontale, un dépôt public ou une URL.

Paramètres usuels de la requête d’autorisation : client_id, redirect_uri (exactement enregistrée), scope, state (anti-CSRF), et le cas échéant code_challenge.

Scopes

openid — identité OpenID ; nécessaire pour recevoir un id_token.
email — adresse e-mail associée au compte Ayeba.
profile — nom affiché et éléments de profil.

Demandez uniquement ce dont votre produit a réellement besoin. Un usage excessif des scopes peut retarder ou empêcher la vérification de l’application.

Clients publics (PKCE)

Pour les applications qui ne peuvent pas conserver un secret (certaines SPA, clients natifs), utilisez PKCE avec la méthode S256 : un code_challenge à l’étape d’autorisation, puis le code_verifier lors de l’échange de jetons. Même dans ce cas, validez toujours le paramètre state et restreignez les redirect URIs.

Profil utilisateur

Après obtention d’un access_token, votre serveur peut consulter l’endpoint userinfo (découvert via OpenID Configuration) pour lire l’identifiant stable sub et, selon les scopes accordés, l’e-mail et le profil. Traitez sub comme clé primaire d’identité côté votre application — pas l’e-mail seul, qui peut évoluer.

Bonnes pratiques

Échangez les codes et stockez les secrets uniquement côté serveur.
Utilisez HTTPS en production pour toutes les redirect URIs.
Vérifiez le paramètre state à chaque retour d’autorisation.
Révoquez et régénérez un secret dès qu’il a pu être exposé.
Informez clairement vos utilisateurs de l’usage que vous faites de leurs données.
Respectez la politique développeurs et les droits des personnes décrits sur ayeba.app/droits.

Intégrer Se connecter avec Ayeba