OAuth

Les routes sont relatives à <PUBLIC_BASE_URL> ; les corps de requête et de réponse sont en JSON sauf mention contraire. L’authentification, les portées, la pagination et le format des erreurs sont décrits dans les guides de l’API REST.

GET /api/v1/admin/oauth-apps/{provider}

Décrire une application OAuth

Rend l’URL de callback et les scopes même sans application enregistrée : ce dont l’administrateur a besoin pour la créer dans la console du fournisseur. Jamais le secret, seulement un repère de quatre caractères.

Accès — Session de membre ou clé d’API portant admin:read (rôle administrateur requis).

Paramètres

Nom	Où	Type	Requis
provider	chemin	string	oui

Réponses

200 — L’état de l’application.

Champ	Type	Requis
provider	"google" | "microsoft"	oui
configured	boolean	oui
clientId	string | null	oui
hasSecret	boolean	oui
clientSecretHint	string | null	oui
status	"active" | "disabled" | null	oui
redirectUri	string (uri)	oui
scopes	string[]	oui
scopesByCapability	object	oui
clientIdPattern	string	oui
clientIdHint	string	oui
updatedAt	string (date-time) | null	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "provider": { "type": "string", "enum": [ "google", "microsoft" ] },
    "configured": { "type": "boolean" },
    "clientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "hasSecret": { "type": "boolean" },
    "clientSecretHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "status": {
      "anyOf": [
        { "type": "string", "enum": [ "active", "disabled" ] },
        { "type": "null" }
      ]
    },
    "redirectUri": { "type": "string", "format": "uri" },
    "scopes": { "type": "array", "items": { "type": "string" } },
    "scopesByCapability": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "enum": [ "mail", "drive", "calendar", "sheets", "files", "sharepoint" ]
      },
      "additionalProperties": { "type": "array", "items": { "type": "string" } }
    },
    "clientIdPattern": { "type": "string", "minLength": 1 },
    "clientIdHint": { "type": "string", "minLength": 1 },
    "updatedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        { "type": "null" }
      ]
    }
  },
  "required": [
    "provider",
    "configured",
    "clientId",
    "hasSecret",
    "clientSecretHint",
    "status",
    "redirectUri",
    "scopes",
    "scopesByCapability",
    "clientIdPattern",
    "clientIdHint",
    "updatedAt"
  ],
  "additionalProperties": false
}

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — oauth.unsupported_provider. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

PUT /api/v1/admin/oauth-apps/{provider}

Enregistrer une application OAuth

Le secret client entre ici et n’en ressort jamais. Refusé quand l’instance n’a pas de clé de chiffrement. L’identifiant client est vérifié contre la forme attendue par le fournisseur. Journalisé dans l’audit (identifiant client seulement).

Accès — Session de membre ou clé d’API portant admin:write (rôle administrateur requis).

Paramètres

Nom	Où	Type	Requis
provider	chemin	string	oui

Corps de la requête (application/json)

Champ	Type	Requis
clientId	string	oui
clientSecret	string	oui
status	"active" | "disabled"	non

Schéma JSON

{
  "type": "object",
  "properties": {
    "clientId": { "type": "string", "minLength": 1, "maxLength": 512 },
    "clientSecret": { "type": "string", "minLength": 1, "maxLength": 512 },
    "status": { "type": "string", "enum": [ "active", "disabled" ] }
  },
  "required": [ "clientId", "clientSecret" ]
}

Réponses

200 — L’état de l’application.

Champ	Type	Requis
provider	"google" | "microsoft"	oui
configured	boolean	oui
clientId	string | null	oui
hasSecret	boolean	oui
clientSecretHint	string | null	oui
status	"active" | "disabled" | null	oui
redirectUri	string (uri)	oui
scopes	string[]	oui
scopesByCapability	object	oui
clientIdPattern	string	oui
clientIdHint	string	oui
updatedAt	string (date-time) | null	oui

Même schéma que GET /api/v1/admin/oauth-apps/{provider}.

400 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — oauth.unsupported_provider, oauth.encryption_disabled, request.bad_request, oauth.invalid_client_id. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.

POST /api/v1/oauth/{provider}/start

Démarrer une connexion OAuth

Rend l’URL d’autorisation vers laquelle envoyer le navigateur. Le corps ne nomme que la capacité (mail par défaut) ; scopes et redirection viennent de l’instance. Exige une application enregistrée pour le fournisseur.

Accès — Session de membre seulement : les clés d’API sont refusées (api_key.session_required).

Paramètres

Nom	Où	Type	Requis
provider	chemin	string	oui

Corps de la requête (application/json)

Champ	Type	Requis
capability	"mail" | "drive" | "calendar" | "sheets" | "files" | "sharepoint"	non

Schéma JSON

{
  "type": "object",
  "properties": {
    "capability": {
      "type": "string",
      "enum": [ "mail", "drive", "calendar", "sheets", "files", "sharepoint" ]
    }
  }
}

Réponses

200 — L’URL d’autorisation et son expiration.

Champ	Type	Requis
authorizationUrl	string (uri)	oui
expiresAt	string (date-time)	oui

Schéma JSON

{
  "type": "object",
  "properties": {
    "authorizationUrl": { "type": "string", "format": "uri" },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [ "authorizationUrl", "expiresAt" ],
  "additionalProperties": false
}

400 — La requête ne respecte pas son schéma.

401 — Aucune session ni clé d’API valide (auth.unauthenticated).

403 — Refusé : rôle insuffisant (auth.forbidden), portée manquante (api_key.scope_missing, details.required la nomme) ou route fermée aux clés (api_key.session_required).

429 — La clé d’API dépasse son débit (api_key.rate_limited) ; Retry-After dit quand réessayer.

Codes d’erreur — oauth.unsupported_provider, request.bad_request, oauth.app_not_configured, oauth.capability_not_supported, oauth.encryption_disabled. Les codes communs (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) s’appliquent à toutes les routes ; voir Erreurs.