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_*). Le header HTTP primaire est X-API-Key (utilisé par les SDKs et la quasi-totalité des routes API). Le header X-Tenant-Key est legacy : il reste accepté sur quelques routes multi-tenant URL-nested (/v1/tenant/*) mais aucun nouveau code ne devrait s'appuyer dessus. 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-API-Key: sk_*`	`sk_live_` / `sk_test_`	Appels API serveur (factures, signatures, devis, billing) — header primaire
Secret Key (legacy)	`X-Tenant-Key: sk_*`	`sk_live_` / `sk_test_`	Même clé secrète, accepté sur les routes multi-tenant URL-nested `/v1/tenant/*` (legacy)
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

bash

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 :

json

{
  "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

bash

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 :

json

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

Consulter son profil

bash

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

Se déconnecter

bash

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.

bash

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

Réponse 201 :

json

{
  "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.

bash

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.

bash

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

Réponse :

json

{
  "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)

bash

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

Les routes legacy /v1/tenant/* acceptent aussi le header X-Tenant-Key: sk_* (même clé), mais le header primaire pour toute l'API reste X-API-Key.

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.

Modele d'authentification — cle = tenant (depuis 2026-05-11)

Une cle sk_* appartient a un tenant master. Aucune contrainte de company_id sur la cle. Le scope d'emission depend du payload :

Cas	Comportement
Pas de `sub_tenant_id` dans le payload	Action au nom du tenant master, company emettrice = `tenant.default_company_id`
`sub_tenant_id` dans le payload	Action au nom du sub-tenant, company emettrice = premiere company du sub-tenant. Le sub-tenant doit appartenir au tenant courant (anti-IDOR `404`)

Erreurs possibles

Code	HTTP	Cause
`TENANT_NOT_RESOLVED`	401	Cle valide mais sans user/tenant rattache (etat anormal)
`SUB_TENANT_NOT_FOUND`	404	`sub_tenant_id` fourni mais hors scope du tenant
`NO_ISSUER_COMPANY`	422	Pas de company emettrice (tenant sans `default_company_id` et pas de sub-tenant fourni)
`KYB_REQUIRED`	403	Production, tenant master sans KYB complete
`SUB_TENANT_NOT_READY`	403	Production, sub-tenant onboarding pas encore verifie (`canIssueInvoices() === false`)
`KYC_REQUIRED`	403	Production, company emettrice sans KYC complete

Le 403 COMPANY_REQUIRED de l'ancien modele est supprime. Les checks KYB/KYC/onboarding sont effectues uniquement en production (sk_live_*). En sandbox (sk_test_*), ils sont skip pour faciliter le developpement.

Routes alternatives URL-nested

Pour la supervision cross-sub-tenant, les routes /v1/tenant/* (middleware tenant.key) sont disponibles et utilisent le meme principe :

GET /v1/tenant/signatures (tenant + tous ses sub-tenants)
GET /v1/tenant/sub-tenants/{subTenantId}/signatures (un sub-tenant precis)
GET /v1/tenant/sub-tenants/{id}/superpdp-status (+ refresh, resume-url)

Publishable Key (widgets client-side)

bash

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

Authentification & Clés API ​

Correspondance des noms de variables d'environnement ​

Vue d'ensemble ​

1. Authentification Bearer Token (Tenant) ​

Créer un compte ​

Se connecter ​

Consulter son profil ​

Se déconnecter ​

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

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

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

Lister ses clés ​

3. Utilisation des clés ​

Secret Key (serveur uniquement) ​

Modele d'authentification — cle = tenant (depuis 2026-05-11) ​

Erreurs possibles ​

Routes alternatives URL-nested ​

Publishable Key (widgets client-side) ​

4. Environnements ​

5. Endpoints de référence ​

6. Sécurité ​

Authentification & Clés API

Correspondance des noms de variables d'environnement

Vue d'ensemble

1. Authentification Bearer Token (Tenant)

Créer un compte

Se connecter

Consulter son profil

Se déconnecter

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

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

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

Lister ses clés

3. Utilisation des clés

Secret Key (serveur uniquement)

Modele d'authentification — cle = tenant (depuis 2026-05-11)

Erreurs possibles

Routes alternatives URL-nested

Publishable Key (widgets client-side)

4. Environnements

5. Endpoints de référence

6. Sécurité