API REST publique

Chaque action de l’interface d’administration de fremforge a son équivalent dans l’API REST publique. L’interface d’administration est elle-même un client de cette surface, et les agents d’IA qui agissent pour le compte d’utilisateurs consomment les mêmes endpoints. Il n’existe aucun endpoint réservé à l’administration et aucune lacune surprise.

Obtenir la spécification

La spécification de référence lisible par machine est au format OpenAPI 3.1.

• YAML : /api/openapi.yaml, la version de référence, en un seul fichier, téléchargeable pour vos outils.
• Miroir JSON : publié à /api/openapi.json au lancement, à partir de la même source, pour les clients qui préfèrent le JSON.

Les deux fichiers sont versionnés avec l’API et mis à jour à chaque release de fremforge. Le champ de version OpenAPI suit MAJOR.MINOR.PATCH ; l’API elle-même est versionnée dans le chemin (/api/v1/...) pour les changements incompatibles.

Authentification

Trois modes d’authentification, déclarés dans la spécification comme des securitySchemes distincts pour que les clients puissent choisir le bon.

Jetons d’accès personnels (PAT), pour les appelants humains et les intégrations CI

Les jetons d’accès personnels sont liés à un utilisateur, pas à une organisation : ils se trouvent donc dans vos paramètres utilisateur sur Forgejo. Rendez-vous sur /<your-user>/settings/applications dans l’interface Forgejo (par exemple frem.sh/<your-user>/settings/applications). Un jeton porte un nom, un ensemble de scopes et une durée de vie (TTL) de 365 jours au maximum, dans la limite du plafond Durée de vie maximale des jetons de l’organisation si votre administrateur en a défini un via la Politique d’authentification. Le jeton brut n’est affiché qu’une seule fois ; seule son empreinte est stockée côté serveur.

À distinguer des jetons d’API d’organisation (décrits plus bas sous Gestion des jetons), qui se trouvent dans l’administration fremforge à /<org>/_admin/api-tokens et survivent au départ d’un membre. Utilisez un PAT pour vos scripts personnels et le développement local ; utilisez un jeton d’API d’organisation pour la CI et l’automatisation en production.

curl -H "Authorization: Bearer ${FREMFORGE_PAT}" \
     https://frem.sh/_app/api/v1/users/me

Identifiants client OAuth 2.0, pour les échanges de machine à machine

Le grant client-credentials standard de la RFC 6749. Enregistrez un client au niveau de l’organisation, puis échangez client_id + client_secret auprès de l’endpoint de jeton :

curl -X POST https://frem.sh/_app/api/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=org:read seats:write"

Échange de jetons OIDC, pour les IdP et les runners de workflow

Lorsque votre IdP peut émettre des JWT OIDC (Authentik, Entra, Okta, Keycloak, …) ou qu’un workflow Forgejo Actions de fremforge doit rappeler l’API, préférez POST /_app/api/v1/auth/token-exchange aux PAT de longue durée. Aucun secret partagé ne quitte votre périmètre, et l’IdP renouvelle la clé sous-jacente selon son propre calendrier.

Émetteurs acceptés :

• IdP du client, enregistré comme entrée auth_sources pour le tenant cible (le même JWKS que celui déjà utilisé pour la connexion des membres). Raccordez d’abord votre IdP depuis la page des paramètres SSO du tenant.
• runner-OIDC de fremforge : les étapes des runners Forgejo Actions peuvent émettre elles-mêmes un jeton fremforge sans aucun raccordement d’IdP supplémentaire. Utilisez le jeton OIDC de runner standard injecté par Forgejo (disponible sous FREMFORGE_OIDC_TOKEN dans l’environnement du job de runner).

Les JWT soumis DOIVENT porter un aud=https://frem.sh/<slug> propre au tenant et un exp récent. Le jeton d’accès renvoyé est un PAT ffp_ ordinaire ; transmettez-le dans les appels suivants sous la forme Authorization: Bearer <token>. Sa durée de vie est plafonnée à 1 heure. Les scopes sont l’intersection de la demande et de la liste d’autorisation de l’échange ; * et tokens:manage ne peuvent jamais être accordés ici. Pour ceux-là, utilisez POST /_app/api/v1/auth/tokens ou l’interface d’administration.

# 1. Mint a JWT from your IdP (aud=https://frem.sh/<your-tenant-slug>).
ASSERTION="$(your-idp-cli get-token --audience https://frem.sh/acme)"

# 2. Exchange it for a short-lived fremforge access token.
ACCESS_TOKEN="$(curl -s -X POST \
  -H 'Content-Type: application/json' \
  -d "{\"subject_token\":\"$ASSERTION\",\"tenant_slug\":\"acme\",\"scopes\":[\"exports:write\",\"exports:read\"]}" \
  https://frem.sh/_app/api/v1/auth/token-exchange | jq -r .access_token)"

# 3. Drive the API with the resulting token (TTL = 1 hour).
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://frem.sh/_app/api/v1/users/me

Depuis une étape de workflow Forgejo Actions, le même flux se présente ainsi :

- name: Exchange runner OIDC for fremforge token
  run: |
    ASSERTION="$FREMFORGE_OIDC_TOKEN"  # injected by fremforge runners
    echo "FREMFORGE_TOKEN=$(curl -sX POST \
      -H 'Content-Type: application/json' \
      -d "{\"subject_token\":\"$ASSERTION\",\"tenant_slug\":\"${{ github.repository_owner }}\",\"scopes\":[\"sboms:write\"]}" \
      https://frem.sh/_app/api/v1/auth/token-exchange | jq -r .access_token)" >> $GITHUB_ENV

L’endpoint est volontairement non authentifié (le JWT tient lieu d’authentification), mais limité à 30 tentatives par minute et par adresse IP source. Au-delà, il renvoie 429 Retry-After. Chaque échange refusé coûte tout de même une vérification RSA : un identifiant d’IdP qui fuit ou une boucle CI défaillante est ainsi contenu au lieu d’être amplifié.

Endpoints par phase et agents agissant pour le compte d’utilisateurs

La spécification OpenAPI utilise l’extension x-fremforge-phase pour indiquer la disponibilité d’un endpoint :

• x-fremforge-phase: 1 : en service et disponible dès maintenant.
• x-fremforge-phase: 2 : spécifié mais pas encore implémenté ; renvoie 501 Not Implemented.

Les endpoints sans cette extension sont en phase 1. Un endpoint qui n’est pas livré renvoie 501 au format RFC 7807 Problem Details, comme toute autre erreur de cette API ; le champ detail indique l’alternative qui fonctionne, lorsqu’il en existe une :

{
  "type": "https://docs.frem.sh/reference/api/errors/not-implemented-yet",
  "title": "Not Implemented",
  "status": 501,
  "detail": "…what to use instead…"
}

Un 501 peut aussi simplement signifier que le chemin ne correspond à rien : la même réponse est renvoyée pour une URL inconnue. Comparez donc votre chemin à la spécification avant de conclure qu’un endpoint n’est pas implémenté.

Il n’existe pas d’identité d’agent. Un agent d’IA agit pour le compte d’une personne : il appelle cette API avec un jeton émis par cette personne, avec un jeton issu d’un échange de jetons RFC 8693 portant l’actor_token de l’agent, ou via un connecteur MCP que la personne a autorisé. Le journal d’audit enregistre la personne comme actor et l’agent comme un détail (fields.agent, avec fields.via_token qui désigne le jeton), et le journal d’audit de l’administration marque ces événements via un agent. GET /orgs/{org}/audit?actor= compare exactement l’acteur, on_behalf_of ou fields.agent : il retrouve donc tout ce qui a été fait pour une personne ou par un agent. Consultez la page Position sur l’IA pour savoir ce qui est en service et ce qui figure sur la feuille de route.

Modèles d’usage par des agents

Trois scénarios de référence autour desquels la spécification a été conçue. Si votre agent a besoin de quelque chose que la spécification ne prend pas proprement en charge, c’est une lacune à signaler : écrivez-nous à support@frem.sh.

Scénario 1 : provisionner une nouvelle organisation à partir d’un mandat délégué

Un agent qui agit pour le compte d’un revendeur ou d’un mandat d’administrateur peut provisionner une organisation complète en quatre appels d’API :

1. POST /orgs : créer l’organisation avec son slug, son nom d’affichage et son contact de facturation
2. PUT /orgs/{org}/sso : configurer le SSO OIDC de la nouvelle organisation
3. POST /orgs/{org}/seats : provisionner le nombre initial d’utilisateurs
4. GET /orgs/{org} : vérifier que l’organisation est active et que le SSO est configuré

Scénario 2 : lire les résultats et créer des pull requests de remédiation

Un mandat en lecture seule. L’agent interroge régulièrement les endpoints des résultats, repère les éléments de gravité élevée et ouvre des pull requests de remédiation via l’interface Git standard de Forgejo (hors du périmètre de cette API REST ; pour cette partie, l’agent utilise Git sur HTTPS ou SSH). Les entrées du journal d’audit nomment la personne pour laquelle l’agent agit, avec l’agent dans fields.agent et une pastille via un agent dans le journal d’audit de l’administration.

Scénario 3 : ajuster la politique d’exécution pendant un incident

Un mandat étroitement limité et borné dans le temps (policy:write:scope=findings-only, valable 1 h). L’agent applique une politique plus stricte (par exemple un blocage de merge sur les CVE CRITICAL dans tous les dépôts) ; la modification est consignée dans le journal d’audit avec la personne comme acteur et l’agent comme détail de l’événement, et les propriétaires de l’organisation la voient dans le journal d’audit lorsqu’ils filtrent sur l’un ou l’autre.

Politique de versionnement

• Versions majeures dans le chemin (/v1/..., /v2/...). Les changements incompatibles sont livrés dans une nouvelle version majeure, avec une période de recouvrement d’au moins 12 mois pendant laquelle les deux versions sont prises en charge.
• Versions mineures et correctives dans info.version. Les nouveaux endpoints, les nouveaux champs facultatifs et les améliorations de la documentation arrivent dans la version majeure en cours sans rompre la compatibilité.
• La spécification OpenAPI fait foi : si un comportement diffère de la spécification, c’est la spécification qui a raison et l’implémentation sera corrigée. Signalez les écarts à support@frem.sh.

Limites de débit

Les requêtes d’API sont limitées par jeton :

Le dépassement d’une limite renvoie HTTP 429 avec un en-tête Retry-After qui indique quand la fenêtre se réinitialise. Les limites s’appliquent par jeton, et non par adresse IP. Les jetons d’API d’organisation et les PAT partagent les mêmes limites par jeton.

Chaque réponse porte aussi les en-têtes IETF RateLimit et RateLimit-Policy conformément à draft-ietf-httpapi-ratelimit-headers. Les limites par jeton et par organisation s’appliquent toutes deux ; la plus restrictive des deux est indiquée dans les en-têtes de la réponse.

Valider la spécification en local

Téléchargez la spécification, puis lancez un linter sur le fichier local :

curl -fsSL https://docs.frem.sh/api/openapi.yaml -o openapi.yaml

# Redocly CLI
npx @redocly/cli@latest lint openapi.yaml

# Swagger CLI
npx @apidevtools/swagger-cli@latest validate openapi.yaml

La spécification passe sans erreur les deux linters ; c’est un engagement bloquant du lancement de la phase 1.

Résultats de sécurité

Chaque analyseur capable de bloquer un merge (analyse statique, dépendances, images de conteneurs, licences) expose ses résultats pour les lister et les écarter :

GET  /orgs/{org}/code-security/{scanner}/findings
POST /orgs/{org}/code-security/{scanner}/findings/{id}/dismiss
POST /orgs/{org}/code-security/{scanner}/findings/bulk-dismiss
PUT  /orgs/{org}/code-security/{scanner}/settings

{scanner} vaut sast, deps, images ou licenses. Ces valeurs ne correspondent pas aux noms des statuts de commit que vous voyez sur une pull request (fremforge/sast, fremforge/dep-scan, fremforge/image-scan, fremforge/license-scan) : déduire le chemin du nom de statut est la façon la plus courante d’obtenir un 501.

Deux autres points à connaître avant d’écrire des scripts contre ces endpoints. Les résultats ne disparaissent pas au merge : ils disparaissent lorsqu’une analyse ultérieure de la même cible ne les signale plus, et un job horaire les résout alors avec dismissed_by: auto-resolve. Écartez-les explicitement lorsque vous acceptez un résultat, ou lorsqu’aucune nouvelle analyse de cette cible n’est prévue. Et licenses ne permet d’écarter qu’un résultat à la fois, sans endpoint groupé.

Les schémas complets des requêtes et des réponses figurent dans la spécification. Pour des exemples curl commentés, consultez l’API des résultats.

Identifiants de registre

Les identifiants en lecture seule propres à votre organisation pour les registres de conteneurs privés (kind: oci) et les hôtes de modules git privés (kind: git). Les analyseurs de fremforge s’en servent pour vérifier les signatures cosign, analyser les images et récupérer les modules Bicep br: et Terraform. Votre CI ne les voit jamais. Lorsque la page d’analyse des images indique qu’un identifiant de registre a expiré ou a été refusé, un propriétaire le remplace ici ou dans la console sous Sécurité › Accès › Identifiants de registre, qui fait la même chose avec les mêmes règles et les mêmes événements d’audit. Les identifiants des registres en amont du proxy de dépendances lui-même (Docker Hub, ghcr.io, quay.io, les registres Red Hat) sont distincts : un propriétaire les gère sous Proxy de dépendances › Identifiants des registres en amont.

GET    /orgs/{org}/registry-credentials             list (policy:read)
PUT    /orgs/{org}/registry-credentials/settings    turn the feature on or off (policy:write)
POST   /orgs/{org}/registry-credentials             add one (policy:write)
PATCH  /orgs/{org}/registry-credentials/{id}        new secret, expiry or both (policy:write)
DELETE /orgs/{org}/registry-credentials/{id}        delete, effective at once (policy:write)

• Propriétaires de l’organisation uniquement. Utilisez un jeton d’API d’organisation avec policy:read pour lister et policy:write pour modifier.
• Le secret est en écriture seule. Il est chiffré au repos et n’est jamais renvoyé. Un identifiant listé affiche fingerprint, expires_at, last_used_at et last_result (ok, refused, expired, rate_limited).
• Un identifiant par hôte et par type. host est le seul nom d’hôte, sans schéma, chemin ni port. expires_at est obligatoire et au plus 366 jours dans le futur. Passé cette date, l’identifiant n’est plus utilisé.
• auth_type vaut basic (username et password, qui peut être un jeton), bearer (token) ou, pour oci uniquement, dockerconfigjson (seule l’entrée de host est conservée).
• Utilisé uniquement pour une analyse de votre organisation. Depuis le 2026-10-23, chaque lecture que les analyseurs de fremforge effectuent avec l’un de vos identifiants doit porter un ticket de courte durée lié à une analyse de votre organisation ; une lecture sans ticket est refusée. Une analyse d’une autre organisation ne peut jamais l’utiliser.
• Activez d’abord la fonctionnalité. Tant qu’elle est désactivée, les analyses n’utilisent aucun identifiant, et aucun ne peut être ajouté ni renouvelé. Vous pouvez toujours en supprimer un. Chaque modification est inscrite au journal d’audit, sans le secret.

Listez les identifiants, puis remplacez le secret et la date d’expiration de celui qui a expiré :

curl -s -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
  https://frem.sh/_app/api/v1/orgs/acme/registry-credentials

curl -s -X PATCH -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"auth_type":"basic","username":"scanner-bot","password":"<new-token>","expires_at":"2027-10-01T00:00:00Z"}' \
  https://frem.sh/_app/api/v1/orgs/acme/registry-credentials/<credential-id>

Ajoutez-en un pour un registre qui n’en a pas encore, ou supprimez-en un :

curl -s -X POST -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"host":"registry.example.com","kind":"oci","auth_type":"bearer","token":"<token>","expires_at":"2027-10-01T00:00:00Z"}' \
  https://frem.sh/_app/api/v1/orgs/acme/registry-credentials

curl -s -X DELETE -H "Authorization: Bearer ${FREMFORGE_TOKEN}" \
  https://frem.sh/_app/api/v1/orgs/acme/registry-credentials/<credential-id>

Les schémas complets des requêtes et des réponses figurent dans la spécification, sous le tag Registry credentials.

Ce que cette spécification ne couvre pas

Deux surfaces sont volontairement hors périmètre :

1. L’API native de Forgejo : les endpoints sous /api/v1/repos, /api/v1/users, /api/v1/issues, /api/v1/pulls, etc. Il s’agit de la surface d’API Forgejo/Gitea que fremforge expose sans modification à https://frem.sh/_app/api/v1/.... Chaque instance fremforge en service sert aussi l’interface Swagger en direct à https://frem.sh/api/swagger (générée directement à partir du Forgejo en service, donc toujours synchronisée avec la version déployée). Les guides de migration renvoient directement à ces endpoints, car ils constituent la surface standard de Forgejo.
2. Les charges utiles des webhooks : les formats des événements de webhook de Forgejo sont définis en amont. L’interface d’administration de fremforge vous permet de configurer les webhooks ; les charges utiles utilisent le vocabulaire d’événements de Forgejo (en-tête X-Forgejo-Event, HMAC-SHA256 X-Forgejo-Signature).

La spécification OpenAPI couvre le plan de contrôle propre à fremforge : organisations, utilisateurs, politiques, résultats, runners, exports, audit, mandats. Tout ce qui existe parce que fremforge l’a ajouté par-dessus Forgejo figure dans cette spécification.

Gestion des jetons

Deux types de jetons sont disponibles.

Types de jetons

Règle générale : utilisez un jeton d’API d’organisation pour tout ce qui tourne en production ou en CI. Utilisez un PAT pour vos outils personnels et vos workflows de développement.

Créer un jeton d’API d’organisation

1. Allez dans Administration de l’organisation → Jetons d’API → Créer un nouveau jeton (frem.sh/<org>/_admin/api-tokens).
2. Saisissez un nom descriptif (par exemple ci-deploy, renovate-bot).
3. Sélectionnez les scopes. Scopes disponibles :

4. Définissez une date d’expiration. La durée de vie par défaut (lorsque ttl_days est omis) est de 90 jours, qui est aussi le maximum : ttl_days accepte de 1 à 90. (Cette page indiquait auparavant 365 ; l’API refuse toute valeur supérieure à 90.) Un jeton ne peut pas être configuré pour ne jamais expirer.
5. Cliquez sur Créer le jeton.

La valeur du jeton n’est affichée qu’une seule fois, à la création. Copiez-la et stockez-la immédiatement dans votre gestionnaire de secrets. fremforge ne stocke pas la valeur brute ; seule son empreinte est conservée côté serveur. Si vous perdez la valeur, révoquez le jeton et créez-en un nouveau.

Créer un PAT

1. Allez dans Paramètres utilisateur → Jetons d’accès Git → Créer un nouveau PAT (frem.sh/user/settings#ff-git-pats).
2. Saisissez un nom, sélectionnez les scopes et définissez une date d’expiration (90 jours par défaut ; 365 jours au maximum).
3. Cliquez sur Créer le PAT.

Les PAT utilisent le même modèle de scopes que les jetons d’API d’organisation. Un PAT hérite des accès de l’utilisateur qui l’a créé, restreints en plus par les scopes sélectionnés.

Isolation des jetons

Les jetons d’API d’organisation sont strictement limités à leur organisation. Un jeton créé dans l’organisation acme ne peut accéder à aucune ressource de l’organisation beta, même si l’utilisateur qui l’a créé est membre des deux organisations. C’est une limite imposée par la plateforme, pas une vérification de permissions qui pourrait être contournée.

Il vous faut donc un jeton d’API d’organisation par organisation pour toute automatisation multi-organisations. Il n’existe aucun type de jeton inter-organisations.

Renouveler un jeton

Renouvelez les jetons lorsqu’ils approchent de leur expiration, lorsqu’un membre de l’équipe qui connaissait la valeur s’en va, ou lorsqu’un jeton a pu être exposé.

Procédure de renouvellement :

1. Créez le nouveau jeton dans Administration de l’organisation → Jetons d’API → Créer un nouveau jeton.
2. Mettez à jour chaque consommateur de l’ancien jeton : secrets CI, configurations de déploiement, fichiers .env, intégrations tierces.
3. Vérifiez que le nouveau jeton fonctionne de bout en bout en déclenchant une exécution de test ou en faisant un appel d’API de test.
4. Révoquez l’ancien jeton dans Administration de l’organisation → Jetons d’API → trouvez le jeton → Révoquer.

Créez d’abord, mettez à jour les consommateurs, puis révoquez. Ne révoquez jamais avant que le remplaçant soit en place.

Révoquer un jeton

1. Allez dans Administration de l’organisation → Jetons d’API (pour les jetons d’API d’organisation) ou Paramètres utilisateur → Jetons d’accès Git (pour les PAT).
2. Trouvez le jeton par son nom.
3. Cliquez sur Révoquer.

La révocation est immédiate. Toute requête qui utilise le jeton révoqué reçoit une réponse 401 Unauthorized. Il n’y a pas de délai de grâce.

Lister les jetons actifs

Administration de l’organisation → Jetons d’API affiche tous les jetons d’API d’organisation avec :

• le nom du jeton
• le nom d’utilisateur de son créateur
• la date de création
• la date de dernière utilisation
• la date d’expiration
• les scopes

Les valeurs des jetons ne sont plus visibles après leur création. Les propriétaires de l’organisation voient toutes les métadonnées des jetons, quel que soit le propriétaire qui les a créés. Seul le créateur du jeton en a vu la valeur, au moment de la création.

Pour les PAT, chaque utilisateur peut lister ses propres jetons dans Paramètres utilisateur → Jetons d’accès Git. Les propriétaires de l’organisation ne peuvent pas énumérer les PAT d’un autre utilisateur, mais les PAT d’un membre retiré perdent automatiquement l’accès aux ressources de l’organisation dès que ce membre en est retiré.

Expiration des jetons

Les jetons expirent automatiquement au terme de leur durée de vie configurée. Un jeton expiré renvoie 401 Unauthorized. Un jeton expiré ne peut pas être prolongé. Créez un nouveau jeton et mettez à jour les consommateurs ; supprimez ensuite, si vous le souhaitez, le jeton expiré de la liste.

Pour éviter les interruptions dues à une expiration passée inaperçue, configurez une alerte dans votre système de supervision à partir de la date d’expiration affichée dans la liste des jetons, ou comptez sur l’e-mail de notification que fremforge envoie 7 jours avant l’expiration d’un jeton d’API d’organisation (envoyé aux propriétaires de l’organisation).

Bonnes pratiques de sécurité

• Stockez les jetons sous forme de secrets CI chiffrés, jamais dans des fichiers du dépôt, dans le YAML des workflows ou dans l’historique des commits.
• Utilisez l’ensemble de scopes minimal nécessaire à la tâche. Un jeton qui ne fait que lire des dépôts n’a pas besoin de orgs:write.
• Définissez la durée de vie la plus courte qui reste praticable. La valeur par défaut est de 90 jours, qui est aussi le maximum pour un jeton d’API d’organisation.
• Renouvelez les jetons qui ont pu être exposés plutôt que de supposer qu’ils n’ont pas été utilisés.
• Vérifiez régulièrement les dates de dernière utilisation des jetons. Un jeton qui n’a pas servi depuis 30 jours est peut-être un identifiant oublié d’une intégration mise hors service.

Obtenir de l’aide

Questions sur le comportement de l’API, endpoints manquants ou propositions de nouvelles opérations : support@frem.sh, avec un objet commençant par API -.