Authentification via OAuth 2.0 & Clés API

Sécurisez vos accès à l'API FarmLink par une authentification par jêtons ou par le standard OAuth 2.0 de l'industrie pour les développeurs tiers.

Pourquoi utiliser l'API FarmLink ?

Données agricoles riches

Accédez aux fermes, parcelles, cultures, inventaires et données financières de vos utilisateurs avec leur consentement.

OAuth 2.0 sécurisé

Authentification standard OAuth 2.0 compatible avec tous les frameworks. Vos utilisateurs gardent le contrôle de leurs données.

SDK TypeScript

SDK officiel avec types complets, auto-complétion et gestion d'erreurs intégrée. Zéro configuration.

Scopes granulaires

Demandez uniquement les permissions nécessaires. Les utilisateurs voient exactement ce que vous accédez.

SDK Officiel

Le SDK FarmLink est la manière la plus simple d'intégrer notre API. TypeScript natif, zéro dépendance, tree-shakeable.

Installation

pnpm (recommandé)

pnpm add @florynxlabs/farmlink-sdk

npm

npm install @florynxlabs/farmlink-sdk

yarn

yarn add @florynxlabs/farmlink-sdk

Démarrage rapide

import { FarmLinkClient } from '@florynxlabs/farmlink-sdk'

// Initialiser le client avec une API Key
const farmlink = new FarmLinkClient({
  apiKey: process.env.FARMLINK_API_KEY
})

// Ou avec un token OAuth
const farmlink = new FarmLinkClient({
  accessToken: 'user_access_token'
})

// Récupérer le profil utilisateur
const user = await farmlink.me()
console.log(user.name)

// Lister les cultures
const cultures = await farmlink.cultures.list()
console.log(cultures.data)

// Créer une culture
const newCulture = await farmlink.cultures.create({
  nom: 'Maïs',
  parcelleId: 'parcelle_id',
  dateDebut: '2024-03-01',
  statut: 'SEMIS'
})

Ressources disponibles

farmlink.fermes

Gestion des fermes

farmlink.parcelles

Gestion des parcelles

farmlink.cultures

Gestion des cultures

farmlink.transactions

Budget et finances

farmlink.inventory

Gestion du stock

farmlink.me()

Profil utilisateur

Gestion des erreurs

import { 
  FarmLinkClient, 
  AuthenticationError, 
  ValidationError,
  NotFoundError,
  RateLimitError 
} from '@florynxlabs/farmlink-sdk'

try {
  const culture = await farmlink.cultures.get('invalid_id')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Culture non trouvée')
  } else if (error instanceof AuthenticationError) {
    console.log('Token invalide ou expiré')
  } else if (error instanceof ValidationError) {
    console.log('Données invalides:', error.errors)
  } else if (error instanceof RateLimitError) {
    console.log('Trop de requêtes, réessayer dans:', error.retryAfter)
  }
}

OAuth 2.0

Utilisez OAuth 2.0 pour permettre aux utilisateurs FarmLink de connecter leur compte à votre application de manière sécurisée.

📋 Résumé pour intégration rapide

Authorization URL: https://farmlinkmali.com/api/oauth/authorize

Token URL: https://farmlinkmali.com/api/oauth/token

UserInfo URL: https://farmlinkmali.com/api/oauth/userinfo

Discovery: https://farmlinkmali.com/.well-known/openid-configuration

Grant Types: authorization_code, refresh_token, client_credentials

PKCE: Supporté (S256)

1. Créer une application OAuth

Connectez-vous à votre compte FarmLink
Allez dans Paramètres → Développeur → Applications
Cliquez sur Créer une application
Remplissez les informations requises :
- Nom de l'application
- Description
- URL de redirection (callback URL)
- Scopes requis
Notez votre Client ID et Client Secret

2. Flux d'autorisation

Étape 1 : Rediriger l'utilisateur

GET https://farmlinkmali.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=read:profile read:cultures
  &state=random_state_string

Étape 2 : Échanger le code contre un token

POST https://farmlinkmali.com/api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "https://your-app.com/callback"
}

Réponse :

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "scope": "read:profile read:cultures"
}

Étape 3 : Utiliser le token

GET https://farmlinkmali.com/api/v1/cultures
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Scopes disponibles

Scope	Description
read:profile	Lire le profil utilisateur
read:fermes	Lire les fermes
read:parcelles	Lire les parcelles
read:cultures	Lire les cultures
write:cultures	Créer/modifier des cultures
read:budget	Lire les données financières
write:budget	Créer/modifier des transactions
read:inventaire	Lire l'inventaire
write:inventaire	Créer/modifier l'inventaire

API Keys

Les API Keys sont idéales pour les intégrations serveur-à-serveur où l'authentification utilisateur n'est pas nécessaire.

Générer une API Key

Allez dans Paramètres → Développeur → API Keys
Cliquez sur Générer une nouvelle clé
Sélectionnez les scopes nécessaires
Copiez la clé immédiatement (elle ne sera plus affichée)

Utiliser une API Key

GET https://farmlinkmali.com/api/v1/cultures
X-API-Key: fl_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxx

Sécurité des API Keys

Ne jamais exposer une API Key côté client (navigateur)
Utiliser des variables d'environnement
Régénérer les clés compromises immédiatement
Utiliser des clés différentes pour dev/prod

Intégration Better Auth

FarmLink OAuth est entièrement compatible avec Better Auth. Voici comment l'intégrer dans votre application.

Configuration Better Auth

// auth.ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  // ... autres options
  
  socialProviders: {
    farmlink: {
      clientId: process.env.FARMLINK_CLIENT_ID!,
      clientSecret: process.env.FARMLINK_CLIENT_SECRET!,
      
      // Endpoints FarmLink OAuth
      authorization: "https://farmlinkmali.com/api/oauth/authorize",
      token: "https://farmlinkmali.com/api/oauth/token",
      userinfo: "https://farmlinkmali.com/api/oauth/userinfo",
      
      // Ou utiliser la découverte automatique
      // issuer: "https://farmlinkmali.com",
      
      // Scopes demandés
      scope: ["openid", "profile", "email", "read:cultures"],
      
      // Mapper les données utilisateur
      profile: (profile) => ({
        id: profile.sub,
        name: profile.name,
        email: profile.email,
        image: profile.picture,
      }),
    },
  },
});

Utilisation côté client

// components/login-button.tsx
import { authClient } from "@/lib/modules/auth/auth-client";

export function LoginWithFarmLink() {
  const handleLogin = async () => {
    await authClient.signIn.social({
      provider: "farmlink",
      callbackURL: "/dashboard",
    });
  };

  return (
    <button onClick={handleLogin}>
      Se connecter avec FarmLink
    </button>
  );
}

Variables d'environnement

# .env
FARMLINK_CLIENT_ID=fl_xxxxxxxxxxxxxxxx
FARMLINK_CLIENT_SECRET=fls_xxxxxxxxxxxxxxxxxxxxxxxx

Découverte OpenID Connect

FarmLink expose un endpoint de découverte OpenID Connect pour la configuration automatique :

GET https://farmlinkmali.com/.well-known/openid-configuration

Cet endpoint retourne tous les URLs et capacités du serveur OAuth.

Exemples de code

Node.js

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://farmlinkmali.com/api/v1',
  headers: {
    'X-API-Key': process.env.FARMLINK_API_KEY
  }
});

// Récupérer les cultures
const { data } = await client.get('/cultures');
console.log(data);

Python

import requests
import os

headers = {
    'X-API-Key': os.environ['FARMLINK_API_KEY']
}

response = requests.get(
    'https://farmlinkmali.com/api/v1/cultures',
    headers=headers
)

cultures = response.json()
print(cultures)

cURL

curl -X GET "https://farmlinkmali.com/api/v1/cultures" \
  -H "X-API-Key: fl_xxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"