Guide d'authentification

Apprenez à vous authentifier avec l'API Stockaj et à gérer les tokens d'accès.

Types de tokens

Stockaj utilise des tokens Laravel Sanctum. Il existe deux contextes de tokens :

Type	Créé par	Cas d'utilisation
Token utilisateur	Utilisateur via profil/API	Accès complet à l'API limité aux permissions de l'utilisateur
Token d'instance	Admin de l'espace de travail via Paramètres	Accès API au niveau de l'espace de travail avec contrôle fin des capacités

Pour la plupart des intégrations, les Tokens d'instance sont recommandés — ils sont liés à un espace de travail et ont un contrôle explicite des capacités.

Création de tokens

Via l'interface web

1. Allez dans Paramètres → Tokens API.
2. Cliquez sur + Nouveau token.
3. Nommez votre token (ex. : scanner-entrepot-prod).
4. Sélectionnez les capacités.
5. Cliquez sur Créer et copiez immédiatement le token.

attention

Le token n'est affiché qu'une seule fois au moment de la création. Si vous le perdez, vous devrez en créer un nouveau.

Conventions de nommage des tokens

Utilisez des noms descriptifs qui indiquent l'objectif et l'environnement du token :

scanner-entrepot-prod
sync-inventaire-staging
app-mobile-v2
ci-testing

Utilisation des tokens

En-tête HTTP

Incluez le token dans l'en-tête Authorization :

Authorization: Bearer VOTRE_TOKEN_API

Exemple complet

curl -X GET "https://app.stockaj.com/api/v2/items" \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://app.stockaj.com/api/v2/items', {
  headers: {
    'Authorization': 'Bearer VOTRE_TOKEN_API',
    'Accept': 'application/json',
  },
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://app.stockaj.com/api/v2/items',
    headers={
        'Authorization': 'Bearer VOTRE_TOKEN_API',
        'Accept': 'application/json',
    },
)
data = response.json()

PHP

$response = Http::withToken('VOTRE_TOKEN_API')
    ->acceptJson()
    ->get('https://app.stockaj.com/api/v2/items');

$data = $response->json();

Capacités des tokens

Contrôlez ce que chaque token peut faire avec des capacités granulaires :

Capacités en lecture seule

Capacité	Ressources
items:read	Articles, variantes, types, tags
renters:read	Locataires
rents:read	Locations
webhooks:read	Webhooks
notifications:read	Notifications
instance:read	Paramètres de l'espace de travail

Capacités en écriture

Capacité	Ressources
items:create	Créer des articles, variantes, types, tags
items:update	Modifier des articles, variantes, types, tags
items:delete	Supprimer/restaurer des articles, variantes, types, tags
renters:create	Créer des locataires
renters:update	Modifier des locataires
renters:delete	Supprimer/restaurer des locataires
rents:create	Créer des locations
rents:update	Modifier des locations
rents:delete	Supprimer des locations

Capacités spéciales

Capacité	Objectif
kiosk:scan	Utiliser les endpoints de scan et recherche kiosque
webhooks:manage	Créer/modifier/supprimer des webhooks
notifications:manage	Gérer l'état des notifications et les préférences
instance:manage	Mettre à jour les paramètres de l'espace de travail

Bonnes pratiques de sécurité

1. Principe du moindre privilège — N'accordez que les capacités dont votre intégration a réellement besoin.
2. Tokens séparés par intégration — Utilisez des tokens différents pour différents services afin de pouvoir les révoquer indépendamment.
3. Rotation régulière des tokens — Créez périodiquement de nouveaux tokens et retirez les anciens.
4. Ne commitez jamais de tokens — Utilisez des variables d'environnement ou des gestionnaires de secrets.
5. HTTPS uniquement — Les tokens sont envoyés dans les en-têtes ; HTTPS empêche l'interception.
6. Surveillez l'utilisation — Examinez les patterns d'accès API et révoquez les tokens inutilisés.

Réponses d'erreur

401 Non autorisé

Le token est manquant, invalide ou expiré :

{
  "message": "Unauthenticated."
}

403 Interdit

Le token n'a pas la capacité requise :

{
  "message": "This action is unauthorized."
}

Résolution : Créez un nouveau token avec les capacités nécessaires, ou mettez à jour les permissions du token existant.