Authentification & Clés API

Scell.io propose 3 modes d'authentification selon le contexte d'utilisation.

Correspondance des noms de variables d'environnement

Nom dans votre .env	Format réel	Où le trouver
SCELL_API_KEY	sk_live_* / sk_test_*	Dashboard > Paramètres > Clés API > Clé secrète
SCELL_TENANT_KEY	sk_live_* / sk_test_*	Même clé que SCELL_API_KEY
SCELL_PUBLIC_KEY	pk_live_* / pk_test_*	Dashboard > Paramètres > Clés API > Clé publishable (partenaires)
SCELL_WEBHOOK_SECRET	whsec_*	Dashboard > Webhooks > Secret (généré par webhook)

Note : SCELL_API_KEY et SCELL_TENANT_KEY désignent la même clé secrète (sk_*). La différence est uniquement le header HTTP utilisé : X-API-Key pour les intégrations partenaires, X-Tenant-Key pour les routes multi-tenant. Vous n'avez qu'une seule clé secrète à gérer.

---

Vue d'ensemble

Mode	Header	Préfixe	Usage
Bearer Token	Authorization: Bearer {token}	—	Dashboard Tenant, gestion de compte
Secret Key	X-Tenant-Key: sk_*	sk_live_ / sk_test_	Appels API serveur (factures, signatures)
Publishable Key	X-Publishable-Key: pk_*	pk_live_ / pk_test_	Widgets client-side (onboarding)

---

1. Authentification Bearer Token (Tenant)

Mode principal (Dashboard SPA) : Le frontend scell.io utilise le mode Sanctum SPA avec des cookies HttpOnly, Secure, SameSite=Strict. Le navigateur appelle d'abord GET /sanctum/csrf-cookie pour obtenir le jeton CSRF, puis effectue le login. Les requetes suivantes sont authentifiees automatiquement via le cookie de session -- aucun token a gerer cote client.

Fallback Bearer token : Les exemples curl ci-dessous et les clients API externes (Postman, scripts serveur, integrations tierces) utilisent le Bearer token retourne au login. Ce mode reste pleinement supporte.

Créer un compte

curl -X POST https://api.scell.io/api/v1/tenant/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "auth_email": "contact@monentreprise.fr",
    "password": "motdepasse123",
    "password_confirmation": "motdepasse123",
    "legal_name": "Mon Entreprise SAS",
    "siret": "12345678901234"
  }'

Réponse 201 :

{
  "message": "Compte créé avec succès.",
  "tenant": {
    "id": "uuid",
    "legal_name": "Mon Entreprise SAS",
    "auth_email": "contact@monentreprise.fr",
    "siret": "12345678901234",
    "environment": "sandbox"
  },
  "access_token": "1|abc123...",
  "token_type": "Bearer"
}

Se connecter

curl -X POST https://api.scell.io/api/v1/tenant/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "auth_email": "contact@monentreprise.fr",
    "password": "motdepasse123"
  }'

Réponse 200 :

{
  "message": "Connexion réussie.",
  "tenant": { "id": "uuid", "legal_name": "...", "auth_email": "...", "environment": "sandbox" },
  "access_token": "2|xyz789...",
  "token_type": "Bearer"
}

Consulter son profil

curl https://api.scell.io/api/v1/tenant/auth/me \
  -H "Authorization: Bearer 2|xyz789..."

Se déconnecter

curl -X POST https://api.scell.io/api/v1/tenant/auth/logout \
  -H "Authorization: Bearer 2|xyz789..."

---

2. Génération de clés API

Générer une Secret Key (sk_*)

La secret key est utilisée pour les appels API serveur. Elle n'est affichée qu'une seule fois.

curl -X POST https://api.scell.io/api/v1/tenant/auth/keys/secret \
  -H "Authorization: Bearer {token}"

Réponse 201 :

{
  "message": "Clé secrète générée. Conservez-la, elle ne sera plus affichée.",
  "secret_key": "sk_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "prefix": "sk_test_"
}

Important

Conservez votre secret key en lieu sûr. Elle est hashée en SHA-256 en base de données et ne pourra plus être récupérée.

Générer une Publishable Key (pk_*)

Réservée aux partenaires (is_partner = true). Utilisée dans les widgets client-side.

curl -X POST https://api.scell.io/api/v1/tenant/auth/keys/publishable \
  -H "Authorization: Bearer {token}"

Lister ses clés

Retourne uniquement les préfixes, jamais les clés complètes.

curl https://api.scell.io/api/v1/tenant/auth/keys \
  -H "Authorization: Bearer {token}"

Réponse :

{
  "keys": [
    { "type": "secret", "prefix": "sk_test_", "hint": "sk_test_••••••••" },
    { "type": "publishable", "prefix": "pk_test_", "hint": "pk_test_••••••••" }
  ]
}

---

3. Utilisation des clés

Secret Key (serveur uniquement)

curl -X POST https://api.scell.io/api/v1/tenant/invoices \
  -H "X-Tenant-Key: sk_test_aBcDeFgH..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Ne jamais exposer côté client

La secret key donne accès complet à votre compte (factures, signatures, billing). Ne l'incluez jamais dans du code frontend, des apps mobiles ou des dépôts publics.

Publishable Key (widgets client-side)

curl -X POST https://api.scell.io/api/v1/tenant/onboarding/sessions \
  -H "X-Publishable-Key: pk_test_aBcDeFgH..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

La publishable key ne donne accès qu'aux endpoints d'onboarding. Elle est conçue pour être exposée dans le navigateur.

---

4. Environnements

Environnement	Préfixes	Données réelles
Sandbox	sk_test_* / pk_test_*	Non — données de test
Production	sk_live_* / pk_live_*	Oui — facturation réelle

---

5. Endpoints de référence

Méthode	Route	Auth	Description
POST	/v1/tenant/auth/register	Aucune	Créer un compte Tenant
POST	/v1/tenant/auth/login	Aucune	Connexion → access_token
POST	/v1/tenant/auth/logout	Bearer	Révoquer le token
GET	/v1/tenant/auth/me	Bearer	Profil Tenant
POST	/v1/tenant/auth/keys/secret	Bearer	Générer sk_*
POST	/v1/tenant/auth/keys/publishable	Bearer	Générer pk_* (partenaires)
GET	/v1/tenant/auth/keys	Bearer	Lister les préfixes de clés

---

6. Sécurité

• Les tokens Bearer expirent après 30 jours
• À chaque login, les tokens précédents sont révoqués
• Les clés sk_/pk_ sont stockées en hash SHA-256 — la clé en clair n'est retournée qu'à la génération
• Le rate limiting s'applique sur les endpoints publics (register, login)
• Les comptes inactifs (is_active = false) sont bloqués au login