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
`first_name`	Prénom	Votre prénom
`name`	Nom	Votre nom de famille

Donnees providers

Acces aux donnees verifiees depuis les providers OAuth connectes :

Scope	Label	Provider
`discord_id`	Id	Discord
`discord_username`	Username	Discord
`discord_avatar`	Avatar	Discord
`discord_discriminator`	Discriminator	Discord
`discord_public_flags`	Public flags	Discord
`discord_flags`	Flags	Discord
`discord_banner`	Banner	Discord
`discord_accent_color`	Accent color	Discord
`discord_global_name`	Global name	Discord
`discord_banner_color`	Banner color	Discord
`discord_mfa_enabled`	Mfa enabled	Discord
`discord_locale`	Locale	Discord
`discord_premium_type`	Premium type	Discord
`discord_email`	Email	Discord
`discord_verified`	Verified	Discord

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