API docs by Redocly

Authentification (1.0.0)

Download OpenAPI specification:

API Support: support@sinoia.fr

Authentification commune à toutes les APIs de la plateforme (Hubdoc, Loctavia, Octopia). Un seul serveur OAuth2 (Doorkeeper) délivre les tokens ; chaque produit consomme ensuite le même Bearer.

Obtenir un token

Cas d'usage Flow Endpoints
Application frontend / tierce Authorization code GET /oauth/authorize puis POST /oauth/token
Application de confiance (mobile, tests) Password POST /oauth/token
CLI hubdoc (sans navigateur) Device flow (RFC 8628 simplifié) POST /api/v1/cli/auth/device puis polling
SSO Edifice (JWT) Token exchange POST /api/v1/oauth/token_exchange
Intégrations serveur Personal Access Token (PAT) généré depuis l'interface ou via le device flow CLI

Scopes

Les scopes sont appliqués par verbe HTTP sur toutes les APIs :

  • read : requêtes GET uniquement (scope par défaut des PAT)
  • write : inclut les mutations (POST, PATCH, PUT, DELETE)
  • admin : accès administratif

Un token sans le scope requis reçoit un 403 enveloppé ; un token expiré ou révoqué reçoit un 401.

Cas particuliers

  • Loctavia : en plus du Bearer, chaque requête (hors GET /loctavia/api/v1/mandataires) exige l'en-tête X-Mandataire-Id (tenant). Voir la doc Loctavia.
  • Octopia : les connecteurs d'ingestion s'authentifient par clé API (X-Connector-Key), sans OAuth2. Voir la doc Octopia.

Authentication

OAuth2 authentication endpoints

Obtenir un token d'accès OAuth2

Obtenir un token d'accès OAuth2 en utilisant différents flows :

  • password : Pour applications de confiance (mobile, CLI, tests) - envoie email/mot de passe directement
  • authorization_code : Pour applications frontend/tierce - échange un code d'autorisation contre un token
  • refresh_token : Pour rafraîchir un token expiré
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "password" "authorization_code" "refresh_token"

Type d'autorisation OAuth2

client_id
required
string

Identifiant client OAuth2

client_secret
required
string

Secret client OAuth2

username
string

Adresse email de l'utilisateur (requis pour grant_type=password)

password
string

Mot de passe de l'utilisateur (requis pour grant_type=password)

code
string

Code d'autorisation (requis pour grant_type=authorization_code)

redirect_uri
string <uri>

URI de redirection (requis pour grant_type=authorization_code)

refresh_token
string

Jeton de rafraîchissement (requis pour grant_type=refresh_token)

scope
string

Portée des permissions demandées (optionnelle)

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 7200,
  • "refresh_token": "def50200cde4321cfa9...",
  • "scope": "read write",
  • "created_at": 1640995200
}

Initier l'autorisation OAuth2 (flow authorization_code)

Redirige l'utilisateur vers l'interface d'autorisation OAuth2. L'utilisateur doit s'authentifier et autoriser l'application. Après autorisation, l'utilisateur est redirigé vers l'URI spécifiée avec un code d'autorisation.

query Parameters
response_type
required
string
Value: "code"
Example: response_type=code

Type de réponse OAuth2 (toujours "code")

client_id
required
string
Example: client_id=Q0OEEVE5kLDll1uAek5B-rJcXJCtkIoEdPwLvDiQ888

Identifiant client OAuth2

redirect_uri
required
string <uri>
Example: redirect_uri=http://localhost:3000/callback

URI de redirection après autorisation

scope
string
Example: scope=read write

Portée des permissions demandées

state
string
Example: state=random_state_string

Valeur aléatoire pour prévenir les attaques CSRF

Responses

Response samples

Content type
application/json
{
  • "error": "bad_request",
  • "message": "Paramètres de requête invalides"
}

Révoquer un token OAuth2

Révoque un token d'accès ou un refresh token OAuth2. Conforme à RFC 7009 (OAuth 2.0 Token Revocation).

Une fois révoqué, le token ne peut plus être utilisé pour accéder aux ressources protégées.

Request Body schema: application/x-www-form-urlencoded
required
token
required
string

Token à révoquer (access_token ou refresh_token)

token_type_hint
string
Enum: "access_token" "refresh_token"

Indice sur le type de token (optionnel, améliore les performances)

client_id
required
string

Identifiant client OAuth2

client_secret
required
string

Secret client OAuth2

Responses

Response samples

Content type
application/json
{
  • "message": "Token revoked successfully"
}

Échanger un JWT Edifice contre un token d'accès

Permet à Edifice d'authentifier ses utilisateurs dans Corex via un échange de token JWT.

Flow:

  1. Edifice génère un JWT signé (RS256) contenant les informations utilisateur
  2. Corex vérifie la signature via JWKS (JSON Web Key Set)
  3. Si l'utilisateur n'existe pas, il est créé automatiquement
  4. Un token d'accès Doorkeeper est retourné

JWT Claims attendus:

  • sub - Identifiant utilisateur Edifice
  • email - Email de l'utilisateur (requis)
  • first_name - Prénom
  • last_name - Nom
  • iss - Doit être "edifice"
  • aud - Doit être "corex"
  • exp - Timestamp d'expiration
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "urn:ietf:params:oauth:grant-type:jwt-bearer"

Type de grant OAuth2 pour l'échange JWT (RFC 7523)

assertion
required
string

JWT signé par Edifice contenant les informations utilisateur

client_id
required
string

Identifiant de l'application OAuth2

client_secret
required
string

Secret de l'application OAuth2

Responses

Response samples

Content type
application/json
{
  • "access_token": "abc123def456...",
  • "token_type": "Bearer",
  • "expires_in": 7200,
  • "created_at": 1705410000
}

CLI Auth

Endpoints du device flow CLI (RFC 8628). Permettent au binaire hubdoc (cf sinoia/hubdoc-tools) de s'authentifier sans manipulation manuelle de tokens : hubdoc login ouvre le navigateur, l'user confirme, le CLI ramasse son PAT automatiquement.

Démarrer un device flow CLI (RFC 8628)

Initie une session d'authentification "device flow" pour le CLI Hubdoc. Endpoint public — pas d'auth Doorkeeper requise.

Le flow complet :

  1. CLI appelle ce endpoint → reçoit device_code (secret) + user_code (lisible humain, format XXXX-XXXX) + verification_uri.
  2. CLI affiche le user_code à l'utilisateur et ouvre la verification_uri_complete dans son navigateur.
  3. L'user (déjà loggé sur Hubdoc) confirme le code sur la page /cli/activation.
  4. CLI poll /api/v1/cli/auth/device/poll jusqu'à approval.
  5. À l'approval, le poll retourne un access_token (un Personal Access Token utilisable comme Bearer sur toute l'API).

Rate-limited à 20 appels par 5 minutes (par IP).

Responses

Response samples

Content type
application/json
{}

Poll pour récupérer l'access_token (device flow CLI)

Polling endpoint du device flow. Le CLI appelle ce endpoint avec son device_code jusqu'à recevoir un access_token (succès) ou une erreur définitive.

Codes d'erreur (compatibles RFC 6749 §5.2) :

  • authorization_pending (400) : pas encore approuvé, retry
  • expired_token (400) : device_code expiré ou inconnu → recommencer le flow
  • access_denied (400) : session révoquée entre l'approval et le pickup
  • already_consumed (410) : token déjà ramassé par un précédent poll → NE PAS retry
Request Body schema: application/json
required
device_code
required
string

Le secret reçu lors du start

Responses

Request samples

Content type
application/json
{
  • "device_code": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "user": {
    }
}