Openbare REST-API

Elke actie in de beheer-UI van fremforge heeft een equivalent in de openbare REST-API. De beheer-UI is zelf een client van dit oppervlak, en AI-agents die namens gebruikers handelen, gebruiken dezelfde endpoints. Er zijn geen endpoints die alleen voor beheerders zijn en geen onverwachte gaten.

De spec ophalen

De canonieke, machineleesbare specificatie is OpenAPI 3.1.

• YAML: /api/openapi.yaml, canoniek, één bestand, te downloaden voor tooling.
• JSON-spiegel: vanaf de lancering gepubliceerd op /api/openapi.json uit dezelfde bron, voor clients die JSON verkiezen.

Beide bestanden krijgen een versie samen met de API en worden bij elke release van fremforge bijgewerkt. Het versieveld van OpenAPI volgt MAJOR.MINOR.PATCH; de API zelf krijgt voor brekende wijzigingen een versie in het pad (/api/v1/...).

Authenticatie

Er zijn drie manieren om je te authenticeren, in de spec gedeclareerd als aparte securitySchemes, zodat gebruikers de juiste kunnen kiezen.

Persoonlijke toegangstokens (PAT), voor menselijke aanroepers en CI-integraties

Persoonlijke toegangstokens horen bij een gebruiker, niet bij een organisatie, dus ze staan in je gebruikersinstellingen in Forgejo: ga in de Forgejo-UI naar /<your-user>/settings/applications (bijvoorbeeld frem.sh/<your-user>/settings/applications). Een token heeft een naam, een set scopes en een TTL van maximaal 365 dagen, begrensd door de maximale Max PAT lifetime voor de hele organisatie als je beheerder die heeft ingesteld via Authenticatiebeleid. Het ruwe token wordt één keer getoond; aan de serverkant wordt alleen de hash bewaard.

Dit is iets anders dan API-tokens van de organisatie (hieronder behandeld bij Tokenbeheer), die in fremforge-beheer staan op /<org>/_admin/api-tokens en blijven bestaan als individuele leden vertrekken. Gebruik een PAT voor persoonlijke scripts en lokale ontwikkeling; gebruik een API-token van de organisatie voor CI en automatisering in productie.

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

OAuth 2.0 client credentials, voor machine-naar-machine

De standaard client-credentials-grant uit RFC 6749. Registreer een client op organisatieniveau en wissel client_id + client_secret in bij het token-endpoint:

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"

OIDC-tokenuitwisseling, voor IdP’s en workflow-runners

Kan je IdP OIDC-JWT’s aanmaken (Authentik, Entra, Okta, Keycloak, …), of moet een Forgejo Actions-workflow van fremforge terugroepen naar de API, gebruik dan liever POST /_app/api/v1/auth/token-exchange dan langlevende PAT’s. Er verlaat geen gedeeld secret je omgeving, en de IdP roteert de onderliggende sleutel volgens zijn eigen schema.

Geaccepteerde uitgevers:

• IdP van de klant, geregistreerd als item in auth_sources voor de doeltenant (dezelfde JWKS die al wordt gebruikt om leden aan te melden). Koppel je IdP eerst via de pagina met SSO-instellingen van de tenant.
• fremforge runner-OIDC: stappen op een Forgejo Actions-runner kunnen zelf een fremforge-token aanmaken zonder extra IdP-koppeling. Gebruik het standaard runner-OIDC-token dat Forgejo injecteert (beschikbaar als FREMFORGE_OIDC_TOKEN in de omgeving van de runnerjob).

Ingediende JWT’s MOETEN een aud=https://frem.sh/<slug> per tenant en een recente exp hebben. Het teruggegeven toegangstoken is een gewone ffp_-PAT; geef die bij volgende aanroepen mee als Authorization: Bearer <token>. De TTL is hard begrensd op 1 uur. De scopes zijn de doorsnede van het verzoek en de allowlist voor uitwisseling; * en tokens:manage kunnen hier nooit worden toegekend. Gebruik daarvoor POST /_app/api/v1/auth/tokens of de beheer-UI.

# 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

Vanuit een stap in een Forgejo Actions-workflow ziet dezelfde flow er zo uit:

- 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

Het endpoint is bewust zonder authenticatie (de JWT is de authenticatie), maar heeft een rate limit van 30 pogingen per minuut per bron-IP. Pieken daarboven geven 429 Retry-After terug. Elke geweigerde uitwisseling kost nog steeds een RSA-verificatie, dus een uitgelekt IdP-inloggegeven of een ontspoorde CI-lus blijft beperkt in plaats van zich op te stapelen.

Gefaseerde endpoints en agents die namens gebruikers handelen

De OpenAPI-spec gebruikt de extensie x-fremforge-phase om de beschikbaarheid van een endpoint aan te geven:

• x-fremforge-phase: 1: live en nu beschikbaar.
• x-fremforge-phase: 2: gespecificeerd maar nog niet geïmplementeerd; geeft 501 Not Implemented terug.

Endpoints zonder de extensie zijn fase 1. Een endpoint dat nog niet is uitgebracht, geeft 501 terug als RFC 7807 Problem Details, net als elke andere fout van deze API; het veld detail noemt het werkende alternatief als dat er is:

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

Een 501 kan ook gewoon betekenen dat het pad nergens mee overeenkwam: hetzelfde antwoord komt terug voor een onbekende URL, dus controleer je pad tegen de spec voordat je concludeert dat een endpoint niet is geïmplementeerd.

Er bestaan geen agent-identiteiten. Een AI-agent handelt namens een persoon: hij roept deze API aan met een token dat de persoon heeft uitgegeven, met een token uit RFC 8693-tokenuitwisseling dat het actor_token van de agent draagt, of via een MCP-connector die de persoon heeft toegestaan. Het auditlog legt de persoon vast als actor en de agent als detail (fields.agent, waarbij fields.via_token het token noemt), en het auditlog in het beheer markeert zulke gebeurtenissen met via agent. GET /orgs/{org}/audit?actor= matcht exact op de actor, on_behalf_of of fields.agent, dus het vindt alles wat voor een persoon of door één agent is gedaan. Zie de pagina over AI-houding voor wat live is en wat op de roadmap staat.

Gebruikspatronen voor agents

Drie referentiescenario’s waarvoor de spec is ontworpen. Heeft je agent iets nodig wat de spec niet netjes ondersteunt, dan is dat een gat dat je kunt melden: laat het ons weten via support@frem.sh.

Scenario 1: een nieuwe organisatie inrichten vanuit een gedelegeerd mandaat

Een agent die handelt namens een mandaat van een reseller of beheerder, kan een complete organisatie inrichten met vier API-aanroepen:

1. POST /orgs: maak de organisatie aan met slug, weergavenaam en factuurcontact
2. PUT /orgs/{org}/sso: configureer OIDC-SSO voor de nieuwe organisatie
3. POST /orgs/{org}/seats: stel het aanvankelijke aantal gebruikers in
4. GET /orgs/{org}: controleer dat de organisatie actief is en SSO is geconfigureerd

Scenario 2: bevindingen lezen en herstel-PR’s aanmaken

Een mandaat met alleen leesscope. De agent bevraagt de endpoints voor bevindingen, zoekt items met hoge ernst en opent herstel-PR’s via de standaard Git-interface van Forgejo (buiten de scope van deze REST-API; voor dat deel gebruikt de agent Git over HTTPS of SSH). Items in het auditlog noemen de persoon voor wie de agent handelt, met de agent in fields.agent en een label via agent in het auditlog in het beheer.

Scenario 3: runtimebeleid aanpassen tijdens een incident

Een strak afgebakend mandaat met een tijdslimiet (policy:write:scope=findings-only, 1 uur geldig). De agent past strenger beleid toe (bijvoorbeeld merges blokkeren bij CRITICAL CVE’s in alle repositories), de wijziging komt in het auditlog met de persoon als actor en de agent als detail van de gebeurtenis, en eigenaren van de organisatie zien haar in het auditlog als ze op een van beide filteren.

Versiebeleid

• Major-versies in het pad (/v1/..., /v2/...). Brekende wijzigingen komen in een nieuwe majorversie, met een overlap van minimaal 12 maanden waarin beide versies worden ondersteund.
• Minor- en patch-versies in info.version. Nieuwe endpoints, nieuwe optionele velden en verbeteringen aan de documentatie komen binnen de huidige majorversie zonder de compatibiliteit te breken.
• De OpenAPI-spec is de bron van waarheid; wijkt het gedrag af van de spec, dan klopt de spec en wordt de implementatie aangepast. Meld afwijkingen bij support@frem.sh.

Rate limits

API-verzoeken hebben een rate limit per token:

Wie een limiet overschrijdt, krijgt HTTP 429 met een header Retry-After die aangeeft wanneer het venster opnieuw begint. De limieten gelden per token, niet per IP. API-tokens van de organisatie en PAT’s delen dezelfde limieten per token.

Elk antwoord bevat ook de IETF-headers RateLimit en RateLimit-Policy volgens draft-ietf-httpapi-ratelimit-headers. Rate limits per token en per organisatie gelden allebei; de strengste van de twee wordt in de headers van het antwoord gemeld.

De spec lokaal valideren

Download de spec en voer daarna een linter uit op het lokale bestand:

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

De spec komt schoon door beide linters; dat is een toezegging die de lancering van fase 1 blokkeert.

Beveiligingsbevindingen

Elke scanner die een merge kan blokkeren (statische analyse, afhankelijkheden, containerimages, licenties) stelt zijn bevindingen beschikbaar om op te vragen en af te wijzen:

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} is een van sast, deps, images, licenses. Deze komen niet overeen met de namen van de commitstatussen die je op een pull request ziet (fremforge/sast, fremforge/dep-scan, fremforge/image-scan, fremforge/license-scan); het pad afleiden uit de statusnaam is de meest voorkomende manier om een 501 te krijgen.

Nog twee dingen die je moet weten voordat je er scripts tegen schrijft. Bevindingen verdwijnen niet bij een merge: ze verdwijnen wanneer een latere scan van hetzelfde doel ze niet meer meldt, waarna een job die elk uur draait ze afhandelt als dismissed_by: auto-resolve. Wijs expliciet af als je een bevinding accepteert, of als er geen nieuwe scan van dat doel meer wordt verwacht. En licenses biedt alleen afwijzen per stuk, zonder bulk-endpoint.

De volledige schema’s voor verzoeken en antwoorden staan in de spec. Voor uitgewerkte curl-voorbeelden, zie Findings-API.

Registerinloggegevens

De eigen alleen-lezen-inloggegevens van je organisatie voor privé-containerregistries (kind: oci) en privéhosts voor git-modules (kind: git). De scanners van fremforge gebruiken ze om cosign-handtekeningen te controleren, images te scannen en Bicep-br:- en Terraform-modules op te halen. Je CI ziet ze nooit. Meldt de pagina voor image-scanning dat registerinloggegevens verlopen of geweigerd zijn, dan vervangt een eigenaar ze hier of in de console onder Beveiliging › Toegang › Registerinloggegevens, dat hetzelfde doet met dezelfde regels en auditgebeurtenissen. Inloggegevens voor de eigen upstreams van de dependency proxy (Docker Hub, ghcr.io, quay.io, de registries van Red Hat) staan apart: een eigenaar beheert ze onder Proxy voor afhankelijkheden › Upstream-inloggegevens.

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)

• Alleen voor eigenaren van de organisatie. Gebruik een API-token van de organisatie met policy:read om op te vragen en policy:write om te wijzigen.
• Het secret kan alleen worden geschreven. Het wordt versleuteld opgeslagen en nooit teruggegeven. Een opgevraagd inloggegeven toont een fingerprint, expires_at, last_used_at en last_result (ok, refused, expired, rate_limited).
• Eén inloggegeven per host en soort. host is alleen de hostnaam, zonder schema, pad of poort. expires_at is verplicht en ligt hoogstens 366 dagen vooruit. Daarna wordt het inloggegeven niet meer gebruikt.
• auth_type is basic (username en password, dat een token mag zijn), bearer (token), of, alleen voor oci, dockerconfigjson (alleen het item voor host wordt bewaard).
• Alleen gebruikt voor een scan van je organisatie. Sinds 2026-10-23 moet elke leesactie die de scanners van fremforge met een van je inloggegevens doen, een kortlevend ticket dragen dat gebonden is aan een scan van je organisatie; een leesactie zonder ticket wordt geweigerd. Een scan van een andere organisatie kan het nooit gebruiken.
• Zet de functie eerst aan. Zolang ze uit staat, gebruiken scans geen inloggegevens en kunnen er geen worden toegevoegd of geroteerd. Verwijderen kan nog wel. Elke wijziging wordt in het auditlog vastgelegd, zonder het secret.

Vraag de inloggegevens op en vervang dan het secret en de vervaldatum van het exemplaar dat is verlopen:

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>

Voeg er een toe voor een registry die er nog geen heeft, of verwijder er een:

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>

De volledige schema’s voor verzoeken en antwoorden staan in de spec, onder de tag Registry credentials.

Wat deze spec niet dekt

Twee oppervlakken vallen bewust buiten de scope:

1. De eigen API van Forgejo: endpoints onder /api/v1/repos, /api/v1/users, /api/v1/issues, /api/v1/pulls, enzovoort. Dat is het API-oppervlak van Forgejo/Gitea dat fremforge ongewijzigd beschikbaar stelt op https://frem.sh/_app/api/v1/.... Elke draaiende fremforge-instantie serveert ook de live Swagger-UI op https://frem.sh/api/swagger (rechtstreeks gerenderd vanuit de draaiende Forgejo, dus altijd in sync met de uitgerolde versie). De migratiegidsen verwijzen rechtstreeks naar deze endpoints, omdat ze het standaardoppervlak van Forgejo zijn.
2. Payloads van webhookafleveringen: de vorm van de webhookgebeurtenissen van Forgejo wordt upstream bepaald. In de beheer-UI van fremforge configureer je webhooks; de payloads gebruiken het gebeurtenisvocabulaire van Forgejo (header X-Forgejo-Event, HMAC-SHA256 in X-Forgejo-Signature).

De OpenAPI-spec dekt het fremforge-specifieke controlplane: organisaties, gebruikers, beleid, bevindingen, runners, exports, audit, mandaten. Alles wat bestaat omdat fremforge het bovenop Forgejo heeft toegevoegd, staat in deze spec.

Tokenbeheer

Er zijn twee soorten tokens.

Soorten tokens

Vuistregel: gebruik een API-token van de organisatie voor alles wat in productie of CI draait. Gebruik een PAT voor persoonlijke tooling en ontwikkelworkflows.

Een API-token van de organisatie aanmaken

1. Ga naar Organisatiebeheer → API-tokens → Nieuw token aanmaken (frem.sh/<org>/_admin/api-tokens).
2. Geef een beschrijvende naam op (bijvoorbeeld ci-deploy, renovate-bot).
3. Kies scopes. Beschikbare scopes:

4. Stel een vervaldatum in. De standaard-TTL (als ttl_days wordt weggelaten) is 90 dagen, en dat is ook het maximum: ttl_days accepteert 1-90. (Deze pagina noemde eerder 365; de API weigert alles boven 90.) Tokens kunnen niet zo worden ingesteld dat ze nooit verlopen.
5. Klik op Token aanmaken.

De waarde van het token wordt bij het aanmaken precies één keer getoond. Kopieer haar meteen en bewaar haar in je secretsmanager. fremforge bewaart de ruwe waarde niet; aan de serverkant wordt alleen de hash bewaard. Ben je de waarde kwijt, trek het token dan in en maak een nieuw aan.

Een PAT aanmaken

1. Ga naar Gebruikersinstellingen → Git-toegangstokens → Nieuwe PAT aanmaken (frem.sh/user/settings#ff-git-pats).
2. Geef een naam op, kies scopes en stel een vervaldatum in (standaard 90 dagen; maximaal 365 dagen).
3. Klik op PAT aanmaken.

PAT’s gebruiken hetzelfde scopemodel als API-tokens van de organisatie. Een PAT erft de toegang van de gebruiker die het heeft aangemaakt, verder beperkt door de gekozen scopes.

Isolatie van tokens

API-tokens van de organisatie zijn strikt aan de organisatie gebonden. Een token dat is aangemaakt onder organisatie acme heeft geen toegang tot resources in organisatie beta, ook niet als de gebruiker die het token heeft aangemaakt lid is van beide organisaties. Dit is een grens die het platform afdwingt, geen rechtencontrole die kan worden omzeild.

Voor automatisering over meerdere organisaties heb je dus één API-token per organisatie nodig. Er is geen tokensoort die over organisaties heen werkt.

Een token roteren

Roteer tokens als ze bijna verlopen, als een teamlid dat de waarde kende vertrekt, of als een token mogelijk is uitgelekt.

Werkwijze voor rotatie:

1. Maak het nieuwe token aan via Organisatiebeheer → API-tokens → Nieuw token aanmaken.
2. Werk alles bij wat het oude token gebruikt: CI-secrets, uitrolconfiguraties, .env-bestanden, integraties van derden.
3. Controleer of het nieuwe token van begin tot eind werkt door een testrun te starten of een test-API-aanroep te doen.
4. Trek het oude token in via Organisatiebeheer → API-tokens → zoek het token → Intrekken.

Eerst aanmaken, dan gebruikers bijwerken, dan intrekken. Trek nooit in voordat de vervanging klaar is.

Een token intrekken

1. Ga naar Organisatiebeheer → API-tokens (voor API-tokens van de organisatie) of Gebruikersinstellingen → Git-toegangstokens (voor PAT’s).
2. Zoek het token op naam.
3. Klik op Intrekken.

Intrekken werkt direct. Elk verzoek met het ingetrokken token krijgt een antwoord 401 Unauthorized. Er is geen overgangsperiode.

Actieve tokens opvragen

Organisatiebeheer → API-tokens toont alle API-tokens van de organisatie met:

• Naam van het token
• Gebruikersnaam van de maker
• Aanmaakdatum
• Datum van laatste gebruik
• Vervaldatum
• Scopes

Tokenwaarden zijn na het aanmaken niet meer zichtbaar. Eigenaren van de organisatie zien alle metadata van tokens, ongeacht welke eigenaar het token heeft aangemaakt. Alleen de maker van het token zag de waarde bij het aanmaken.

Voor PAT’s kan elke gebruiker zijn eigen tokens opvragen via Gebruikersinstellingen → Git-toegangstokens. Eigenaren van de organisatie kunnen de PAT’s van een andere gebruiker niet opsommen, maar de PAT’s van een verwijderd lid verliezen automatisch de toegang tot resources van de organisatie op het moment dat dat lid uit de organisatie wordt verwijderd.

Verlopen van tokens

Tokens verlopen automatisch na hun ingestelde TTL. Een verlopen token geeft 401 Unauthorized terug. Verlopen tokens kunnen niet worden verlengd. Maak een nieuw token aan en werk de gebruikers ervan bij; verwijder daarna eventueel het verlopen token uit de lijst.

Om storingen door ongemerkt verlopen te voorkomen, stel je in je monitoringsysteem een waarschuwing in op basis van de vervaldatum in de tokenlijst, of vertrouw je op de e-mail die fremforge 7 dagen voordat een API-token van de organisatie verloopt verstuurt (naar de eigenaren van de organisatie).

Goede beveiligingspraktijken

• Bewaar tokens als versleutelde CI-secrets, niet in bestanden in de repository, workflow-YAML of commitgeschiedenis.
• Gebruik de kleinste set scopes die de taak nodig heeft. Een token dat alleen repositories leest, heeft geen orgs:write nodig.
• Stel de kortste TTL in die praktisch werkbaar is. De standaard is 90 dagen, en dat is ook het maximum voor een API-token van de organisatie.
• Roteer tokens die mogelijk zijn uitgelekt, in plaats van aan te nemen dat ze niet zijn gebruikt.
• Controleer regelmatig de datum van laatste gebruik van tokens. Een token dat in 30 dagen niet is gebruikt, kan een vergeten inloggegeven zijn van een integratie die niet meer bestaat.

Hulp krijgen

Vragen over het gedrag van de API, ontbrekende endpoints of voorstellen voor nieuwe bewerkingen: support@frem.sh met een onderwerpregel die begint met API -.