Accounts

Les exemples utilisent $SPAVIK_BASE_URL et $SPAVIK_API_KEY, définis dans Démarrer.

GET /health

État du service et de ses dépendances

Authentification : Route publique, aucune authentification

Réponses

Code	Description
200	Succès

Exemple

curl -X GET "$SPAVIK_BASE_URL/health" \
  -H 'X-API-Key: sk-spv-api-...'

GET /openapi.json

Contrat de l'API (ce document)

Authentification : Route publique, aucune authentification

Réponses

Code	Description
200	Succès

Exemple

curl -X GET "$SPAVIK_BASE_URL/openapi.json" \
  -H 'X-API-Key: sk-spv-api-...'

GET /v1/api-keys

Lister les clés du workspace

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Paramètres

Nom	Où	Type		Description
limit	query	integer	facultatif
offset	query	integer	facultatif

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/api-keys" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/api-keys

Créer une clé d'API

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
name	string	requis
kind	api | admin	facultatif	Une clé « admin » ne se crée que depuis une session web, et son préfixe est sk-spv-admin-.
expires_at	string	facultatif	Facultatif. Sans lui la clé n'expire jamais, ce que veulent les clés de production.

Réponses

Code	Description
201	Créée (le secret n'est rendu qu'une seule fois)
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/api-keys" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "prod",
  "kind": "api"
}'

DELETE /v1/api-keys/{keyId}

Révoquer une clé

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
204	Révoquée
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Clé inconnue.

Exemple

curl -X DELETE "$SPAVIK_BASE_URL/v1/api-keys/{keyId}" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/api-keys/{keyId}/rotate

Remplacer une clé sans couper l'application

Crée une clé jumelle (même portée) et donne à l'ancienne une date de fin, dans sept jours par défaut : les deux fonctionnent pendant la migration. grace_days: 0 révoque l'ancienne immédiatement, pour un secret compromis.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
grace_days	integer	facultatif

Réponses

Code	Description
201	Nouvelle clé (le secret n'est rendu qu'une seule fois)
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
404	Clé inconnue.
409	Clé déjà remplacée.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/api-keys/{keyId}/rotate" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "grace_days": 7
}'

POST /v1/auth/login

Commencer la connexion avec une adresse e-mail

Le point d'entrée unique, pour tout le monde. Envoyez l'adresse et l'API dit la suite : magic_link (un lien et un code ont été envoyés par e-mail, à échanger sur POST /v1/auth/magic-link/verify) ou password (une adresse du staff Spavik : envoyer le mot de passe sur POST /v1/auth/login/password, puis le code reçu sur POST /v1/auth/login/verify).

La réponse ne dépend que du domaine de l'adresse, jamais de l'existence d'un compte.

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
email	string	requis

Réponses

Code	Description
200	Succès

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/login" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "{{email}}"
}'

POST /v1/auth/login/password

Connexion du staff : le mot de passe

Réservé aux adresses du staff Spavik. Le mot de passe est vérifié avant tout envoi de code. En cas de succès, un code à six chiffres est envoyé par e-mail ; échangez-le sur POST /v1/auth/login/verify.

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
email	string	requis
password	string	requis

Réponses

Code	Description
202	Code envoyé
401	STAFF_LOGIN_INVALID : adresse inconnue ou mot de passe erroné.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/login/password" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "{{staff_email}}"
}'

POST /v1/auth/login/verify

Connexion du staff : le code reçu par e-mail

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
email	string	requis
code	string	requis

Réponses

Code	Description
200	Succès
400	OTP_INVALID ou OTP_TOO_MANY_ATTEMPTS.
401	STAFF_LOGIN_INVALID.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/login/verify" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "{{staff_email}}",
  "code": "{{otp_code}}"
}'

POST /v1/auth/logout

Révoquer un jeton de rafraîchissement

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
refresh_token	string	requis

Réponses

Code	Description
204	Révoquée

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/logout" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "refresh_token": "{{refresh_token}}"
}'

POST /v1/auth/magic-link/verify

Échanger le lien ou le code contre des jetons

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
token	string	facultatif
email	string	facultatif
code	string	facultatif

Réponses

Code	Description
200	Succès
400	Lien ou code invalide.
403	STAFF_LOGIN_REQUIRED : une adresse du staff ne se connecte jamais par un lien.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/magic-link/verify" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "{{magic_token}}"
}'

GET /v1/auth/me

Profil, plan et workspaces

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/auth/me" \
  -H 'X-API-Key: sk-spv-api-...'

PATCH /v1/auth/me

Modifier votre profil

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
full_name	string	requis

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X PATCH "$SPAVIK_BASE_URL/v1/auth/me" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{ }'

DELETE /v1/auth/me

Supprimer définitivement votre compte

Efface les workspaces, les modèles (côté moteur compris) et les clés. Confirmez avec votre propre adresse e-mail.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
email	string	requis

Réponses

Code	Description
204	Supprimé
400	La confirmation ne correspond pas.
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X DELETE "$SPAVIK_BASE_URL/v1/auth/me" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "{{email}}"
}'

GET /v1/auth/oauth/{provider}

Démarrer la connexion OAuth (navigateur)

Authentification : Route publique, aucune authentification

Réponses

Code	Description
302	Redirection vers le fournisseur
404	Fournisseur inconnu.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/auth/oauth/{provider}" \
  -H 'X-API-Key: sk-spv-api-...'

GET /v1/auth/oauth/{provider}/callback

Retour du fournisseur (navigateur)

Authentification : Route publique, aucune authentification

Réponses

Code	Description
302	Redirection vers l'interface avec un code
400	État OAuth invalide.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/auth/oauth/{provider}/callback" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/auth/oauth/{provider}/link

Lier un fournisseur au compte connecté

Le seul chemin qui rattache une identité à un compte existant. Une identité inconnue ne prend jamais la main sur un compte au seul motif qu'elle en annonce l'adresse : un jeton valablement signé peut porter une adresse que son porteur ne possède pas.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
code	string	requis

Réponses

Code	Description
204	Lié
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
409	Identité déjà liée à un autre compte.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/oauth/{provider}/link" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{ }'

POST /v1/auth/oauth/exchange

Échanger le code OAuth contre des jetons

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
code	string	requis

Réponses

Code	Description
200	Succès
400	Code invalide ou déjà utilisé.
409	Un compte utilise déjà cette adresse : liez le fournisseur depuis une session connectée.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/oauth/exchange" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{ }'

GET /v1/auth/providers

Méthodes de connexion disponibles

À lire avant de composer un écran de connexion, plutôt que de coder les boutons en dur. Un fournisseur n'est annoncé que si ses identifiants sont configurés : ce qui est absent de cette liste ne peut connecter personne.

Authentification : Route publique, aucune authentification

Réponses

Code	Description
200	Succès

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/auth/providers" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/auth/refresh

Renouveler les jetons

Authentification : Route publique, aucune authentification

Corps de la requête

Nom	Type		Description
refresh_token	string	requis

Réponses

Code	Description
200	Succès
401	Jeton de rafraîchissement invalide.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/auth/refresh" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "refresh_token": "{{refresh_token}}"
}'

GET /v1/geoip

Géolocaliser le visiteur (pour préremplir un formulaire)

Authentification : Route publique, aucune authentification

Réponses

Code	Description
200	Succès
422	PRIVATE_IP : adresse privée ou locale, rien à géolocaliser (développement local et réseaux internes).
503	Géolocalisation indisponible.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/geoip" \
  -H 'X-API-Key: sk-spv-api-...'

GET /v1/workspaces

Lister vos workspaces

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/workspaces" \
  -H 'X-API-Key: sk-spv-api-...'

POST /v1/workspaces

Créer un workspace

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
name	string	requis

Réponses

Code	Description
201	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/workspaces" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My mobile app"
}'

GET /v1/workspaces/{workspaceId}

Détail d'un workspace

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/workspaces/{workspaceId}" \
  -H 'X-API-Key: sk-spv-api-...'

PATCH /v1/workspaces/{workspaceId}

Renommer un workspace

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
name	string	requis

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X PATCH "$SPAVIK_BASE_URL/v1/workspaces/{workspaceId}" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{ }'