Documentation API Konnect

Konnect est un provider OAuth2 qui permet aux utilisateurs de controler finement les donnees qu'ils partagent avec votre application.

Base URL

https://konnect.example.com

Authentification

Konnect utilise le flow OAuth2 Authorization Code avec support PKCE.

Redirigez l'utilisateur vers la page d'autorisation
L'utilisateur accepte les permissions demandees
Echangez le code contre des tokens
Utilisez l'access token pour recuperer les donnees

1. Authorization Request

Redirigez l'utilisateur vers cette URL :

GET /oauth/authorize

Parametres

Parametre	Requis	Description
`client_id`	Oui	Votre Client ID
`redirect_uri`	Oui	URL de callback (doit etre enregistree)
`scope`	Oui	Scopes demandes (separes par espaces)
`state`	Recommande	Protection CSRF
`code_challenge`	PKCE	Challenge PKCE (base64url SHA256)
`code_challenge_method`	PKCE	`S256` 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

Reponse

L'utilisateur est redirige vers votre redirect_uri avec :

url

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

2. Token Exchange

Echangez 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"
}

Reponse

json

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

3. User Info

Recuperez les donnees utilisateur avec l'access token :

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

Reponse

Retourne uniquement les champs que l'utilisateur a accepte 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

Donnees standard

Scope	Label	Description
`adress`	Adresse postale	Votre adresse postale
`child_number`	Nombre d'enfants	Combien avez-vous d'enfants ?
`city`	Ville	Ville de résidence
`country`	Pays	Pays de résidence
`detudes`	Domaine d'études	Votre domaine d'études
`dob`	Date de naissance	Votre date de naissance
`email`	Email	Votre email
`enterprise`	Nom de l'entreprise	Le nom de l'entreprise pour laquelle vous travaillez
`first_name`	Prénom	Votre prénom
`flanguage`	Langue préférée	Votre langage préféré
`genre`	Genre	Votre genre
`hobbies`	Hobbies	Vos hobbies
`language`	Langues parlées	Vos langues parlées
`matrimonial`	Statut matrimonial	Votre statut matrimonial
`name`	Nom	Votre nom de famille
`netudes`	Niveau d'études	Votre niveau d'études
`phone`	Téléphone	Votre numéro de téléphone
`poste`	Poste/Fonction	Votre poste/fonction dans l'entreprise
`prostatus`	Statut professionnel	Votre statut professionnel
`region`	Région	Région de résidence
`salaries`	Taille d'entreprise	Le nombre d'employés de l'entreprise pour laquelle vous travaillez
`username`	Pseudonyme	Votre pseudonyme

Donnees providers

Acces aux donnees verifiees depuis les providers OAuth connectes :

Scope	Label	Provider
`google_id`	Id	Google
`google_email`	Email	Google
`google_verified_email`	Verified email	Google
`google_name`	Name	Google
`google_given_name`	Given name	Google
`google_family_name`	Family name	Google
`google_picture`	Picture	Google

Webhooks

Les webhooks permettent a votre application de recevoir des notifications en temps reel lorsqu'un utilisateur se connecte.

Configuration

Configurez l'URL de votre webhook dans les parametres de votre application sur le dashboard.

Evenement : user.connected

Declenche lorsqu'un nouvel utilisateur autorise votre application pour la premiere 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

Repondez rapidement (< 5 secondes) avec un code 200 pour confirmer la reception
Verifiez l'origine des requetes en validant les donnees recues
Traitez les webhooks de maniere asynchrone si necessaire
Implementez une logique de retry en cas d'echec temporaire

Important

Si votre webhook echoue, le processus d'autorisation n'est pas interrompu. L'utilisateur pourra quand meme utiliser votre application.

Erreurs

Format de reponse en cas d'erreur :

json

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

Codes d'erreur

HTTP	Code	Description
400	`BAD_REQUEST`	Parametres invalides
401	`UNAUTHORIZED`	Token invalide ou expire
403	`FORBIDDEN`	Acces refuse
404	`NOT_FOUND`	Ressource introuvable

PKCE

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

Implementation 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(/=+$/, '')
}