API publique

Taco expose une API REST publique en libre-service sous /api/v1 pour gérer les enregistrements de clients et piloter le workflow d’approbation par programmation. C’est une surface distincte de l’interface interne de revue/administration — voir la limite de périmètre ci-dessous.

Note

La spécification complète, lisible par machine, est toujours servie en direct sur GET /api/v1/openapi.json et reflétée dans public/openapi/v1.json dans le dépôt.

Authentification

L’API est un resource server OAuth2 — elle valide des jetons porteurs (JWT ou opaques) émis par un serveur d’autorisation que vous configurez. Taco n’émet jamais ses propres jetons d’API. Voir les variables API_AUTH_* sur la page Configuration.

Authorization: Bearer <access_token>

Le jeton affirme qui appelle (sub) et ce qu’il peut faire (scope). Il n’affirme jamais quelle organisation — chaque requête le précise explicitement.

Portée organisationnelle

Chaque ressource appartient à une organisation. Il existe deux arborescences de routes équivalentes :

• Explicite (toujours disponible) : /api/v1/organizations/{organizationId}/registrations
• Organisation par défaut (activable via API_DEFAULT_ORGANIZATION_ENABLED=true) : /api/v1/registrations — résout l’organisation à partir du mapping d’organisation par défaut de l’appelant plutôt que d’un segment d’URL.

Un sujet de jeton se voit accorder l’accès à des organisations spécifiques (et peut optionnellement être marqué comme organisation par défaut) depuis Paramètres → Organisation → Accès API, par un administrateur de l’organisation.

GET /api/v1/organizations liste chaque organisation sur laquelle le sujet du jeton de l’appelant peut agir.

Libre-service uniquement

L’API publique n’expose volontairement pas les actions de revue/administration : approve, reject, request-changes, suspend, unsuspend, deprecate, l’approbation/le rejet d’un change set, ni la file de revue et ses commentaires. Un jeton — quel que soit son scope — ne peut pas atteindre ces transitions via cette API ; elles restent accessibles uniquement via l’interface interne de revue. L’API publique permet de créer, modifier, soumettre et retirer un enregistrement dans une organisation autorisée, et de proposer des change sets sur un client actif.

Découvrir ce qui est possible

• GET /api/v1/organizations/{organizationId}/capabilities — restrictions de plan, scopes accordés à l’appelant, types de grant/application disponibles par type de client, contraintes de profils de politique visibles, politique de plateforme, modèles et limites de débit.
• Chaque réponse d’enregistrement/change set inclut un tableau actions (par ex. ["edit", "submit", "delete"]) nommant exactement les transitions en libre-service actuellement permises, pour que l’interface n’ait jamais à deviner à partir des chaînes de statut.

Erreurs

Chaque réponse non-2xx utilise une enveloppe structurée :

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation.",
    "fields": [{ "path": "config.redirectUris", "message": "Invalid url" }],
    "requestId": "..."
  }
}

Voir le document OpenAPI pour l’énumération complète des code.

Référence des points de terminaison

Ressource	Chemin explicite
Enregistrements	GET/POST /api/v1/organizations/{organizationId}/registrations
Enregistrement	GET/PATCH/DELETE .../registrations/{id}
Actions de cycle de vie	POST .../registrations/{id}/actions/{submit|withdraw}
Change sets	GET/POST .../registrations/{id}/change-sets
Change set	GET .../change-sets/{id}
Profils de politique (lecture seule)	GET .../policy-profiles[/{id}]
Modèles (lecture seule)	GET .../templates[/{id}]
Capacités	GET .../capabilities

Chacun des points ci-dessus existe aussi sans préfixe (par ex. POST /api/v1/registrations) quand API_DEFAULT_ORGANIZATION_ENABLED=true.