Documentation API Konnect

Konnect est un provider OAuth2 qui permet aux utilisateurs de contrôler finement les données qu'ils partagent avec votre application.

Base URL

https://konnect.example.com

Authentification

Konnect utilise le flow OAuth2 Authorization Code avec support PKCE.

  1. Redirigez l'utilisateur vers la page d'autorisation
  2. L'utilisateur accepte les permissions demandées
  3. Échangez le code contre des tokens
  4. Utilisez l'access token pour récupérer les données

1. Authorization Request

Redirigez l'utilisateur vers cette URL :

GET /oauth/authorize

Paramètres

ParamètreRequisDescription
client_idOuiVotre Client ID
redirect_uriOuiURL de callback (doit être enregistrée)
scopeOuiScopes demandés (séparés par espaces)
stateRecommandeProtection CSRF
code_challengePKCEChallenge PKCE (base64url SHA256)
code_challenge_methodPKCES256 ou plain

Exemple

url
https://konnect.example.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  scope=first_name last_name email&
  state=random_state_string&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

Réponse

L'utilisateur est redirigé vers votre redirect_uri avec :

url
https://yourapp.com/callback?
  code=kc_a1b2c3d4e5f6...&
  state=random_state_string

2. Token Exchange

Échangez le code d'autorisation contre des tokens :

POST /api/trpc/oauth2.token

Request Body

json
{
  "grant_type": "authorization_code",
  "code": "kc_a1b2c3d4e5f6...",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://yourapp.com/callback",
  "code_verifier": "original_code_verifier"
}

Réponse

json
{
  "access_token": "at_...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "first_name last_name email"
}

3. User Info

Récupérez les données utilisateur avec l'access token :

GET /api/trpc/oauth2.userInfo?input={"accessToken":"..."}

Réponse

Retourne uniquement les champs que l'utilisateur a accepté de partager :

json
{
  "sub": "123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com"
}

Le champ sub (ID utilisateur) est toujours inclus. Les autres champs dependent des consentements accordes.

4. Refresh Token

Obtenez un nouveau access token :

json
{
  "grant_type": "refresh_token",
  "refresh_token": "rt_...",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Scopes disponibles

Données standard

ScopeLabelDescription
adressAdresse postaleVotre adresse postale
child_numberNombre d'enfantsCombien avez-vous d'enfants ?
cityVilleVille de résidence
countryPaysPays de résidence
detudesDomaine d'étudesVotre domaine d'études
dobDate de naissanceVotre date de naissance
emailEmailVotre email
enterpriseNom de l'entrepriseLe nom de l'entreprise pour laquelle vous travaillez
first_namePrénomVotre prénom
flanguageLangue préféréeVotre langage préféré
genreGenreVotre genre
hobbiesHobbiesVos hobbies
languageLangues parléesVos langues parlées
matrimonialStatut matrimonialVotre statut matrimonial
nameNomVotre nom de famille
netudesNiveau d'étudesVotre niveau d'études
phoneTéléphoneVotre numéro de téléphone
postePoste/FonctionVotre poste/fonction dans l'entreprise
prostatusStatut professionnel Votre statut professionnel
regionRégionRégion de résidence
salariesTaille d'entrepriseLe nombre d'employés de l'entreprise pour laquelle vous travaillez
usernamePseudonymeVotre pseudonyme

Données providers

Accès aux données vérifiées depuis les providers OAuth connectés :

ScopeLabelProvider
discord_idIdDiscord
discord_usernameUsernameDiscord
discord_avatarAvatarDiscord
discord_discriminatorDiscriminatorDiscord
discord_public_flagsPublic flagsDiscord
discord_flagsFlagsDiscord
discord_bannerBannerDiscord
discord_accent_colorAccent colorDiscord
discord_global_nameGlobal nameDiscord
discord_banner_colorBanner colorDiscord
discord_mfa_enabledMfa enabledDiscord
discord_localeLocaleDiscord
discord_premium_typePremium typeDiscord
discord_emailEmailDiscord
discord_verifiedVerifiedDiscord

Webhooks

Les webhooks permettent à votre application de recevoir des notifications en temps réel lorsqu'un utilisateur se connecte.

Configuration

Configurez l'URL de votre webhook dans les paramètres de votre application sur le dashboard.

Événement : user.connected

Déclenché lorsqu'un nouvel utilisateur autorise votre application pour la première fois.

POST https://votreapp.com/webhooks/konnect

Payload

json
{
  "event": "user.connected",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "app": {
    "id": 1,
    "name": "Mon Application",
    "clientId": "kc_abc123..."
  },
  "user": {
    "id": 42,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "scope": "first_name last_name email"
}

Bonnes pratiques

  • Répondez rapidement (< 5 secondes) avec un code 200 pour confirmer la réception
  • Vérifiez l'origine des requêtes en validant les données reçues
  • Traitez les webhooks de manière asynchrone si nécessaire
  • Implémentez une logique de retry en cas d'échec temporaire

Important

Si votre webhook échoue, le processus d'autorisation n'est pas interrompu. L'utilisateur pourra quand même utiliser votre application.

Erreurs

Format de réponse en cas d'erreur :

json
{
  "error": {
    "message": "Invalid access token",
    "code": -32600,
    "data": {
      "code": "UNAUTHORIZED",
      "httpStatus": 401
    }
  }
}

Codes d'erreur

HTTPCodeDescription
400BAD_REQUESTParamètres invalides
401UNAUTHORIZEDToken invalide ou expiré
403FORBIDDENAccès refusé
404NOT_FOUNDRessource introuvable

PKCE

Pour les clients publics (apps mobiles, SPA), PKCE est fortement recommandé.

Implémentation JavaScript

javascript
// Generate code verifier (random string)
function generateCodeVerifier() {
  const array = new Uint8Array(32)
  crypto.getRandomValues(array)
  return base64UrlEncode(array)
}

// Generate code challenge (SHA256 hash)
async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder()
  const data = encoder.encode(verifier)
  const hash = await crypto.subtle.digest('SHA-256', data)
  return base64UrlEncode(new Uint8Array(hash))
}

// Base64 URL encoding
function base64UrlEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '')
}