Offentligt REST API

Alle handlinger i fremforges administrationsflade har en tilsvarende handling i det offentlige REST API. Administrationsfladen er selv en klient af dette API, og AI-agenter, der handler på vegne af brugere, bruger de samme endpoints. Der er ingen endpoints, der kun er for administratorer, og ingen overraskende huller.

Hent specifikationen

Den officielle maskinlæsbare specifikation er OpenAPI 3.1.

• YAML: /api/openapi.yaml, den officielle udgave i én fil, som du kan downloade til dine værktøjer.
• JSON-spejl: udgives på /api/openapi.json fra lanceringen, ud fra samme kilde, til klienter, der foretrækker JSON.

Begge filer er versioneret sammen med API’et og opdateres ved hver udgivelse af fremforge. OpenAPI-versionsfeltet følger MAJOR.MINOR.PATCH; selve API’et er versioneret i stien (/api/v1/...) for ændringer, der bryder kompatibiliteten.

Godkendelse

Der er tre måder at godkende på, og de er erklæret i specifikationen som separate securitySchemes, så klienter kan vælge den rigtige.

Personlige adgangstokens (PAT) til menneskelige kaldere og CI-integrationer

Personlige adgangstokens hører til en bruger, ikke en organisation, så de ligger under dine brugerindstillinger i Forgejo: gå til /<your-user>/settings/applications i Forgejos brugerflade (f.eks. frem.sh/<your-user>/settings/applications). Et token har et navn, et sæt scopes og en levetid på op til 365 dage, begrænset af organisationens Maksimal PAT-levetid, hvis din administrator har sat en via Godkendelsespolitik. Selve tokenet vises én gang; serveren gemmer kun dets hash.

De adskiller sig fra organisationens API-tokens (beskrevet nedenfor under Håndtering af tokens), som ligger i fremforges administration på /<org>/_admin/api-tokens og overlever, at enkelte medlemmer forlader organisationen. Brug en PAT til personlige scripts og lokal udvikling; brug et API-token for organisationen til CI og automatisering i produktion.

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

OAuth 2.0 client credentials til maskine-til-maskine

Et almindeligt client credentials-grant efter RFC 6749. Registrér en klient på organisationsniveau, og veksl client_id + client_secret ved token-endpointet:

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-tokenudveksling til IdP’er og workflow-runners

Når din IdP kan udstede OIDC-JWT’er (Authentik, Entra, Okta, Keycloak, …), eller når et Forgejo Actions-workflow i fremforge skal kalde tilbage til API’et, så foretræk POST /_app/api/v1/auth/token-exchange frem for langlivede PAT’er. Ingen delt hemmelighed forlader dit område, og IdP’en roterer den underliggende nøgle efter sin egen plan.

Accepterede udstedere:

• Kundens IdP, registreret som en auth_sources-post for den pågældende tenant (det samme JWKS, som allerede bruges til medlemmers login). Forbind først din IdP fra tenantens side med SSO-indstillinger.
• fremforges runner-OIDC: trin i Forgejo Actions-runners kan selv udstede et fremforge-token uden ekstra IdP-opsætning. Brug det almindelige runner-OIDC-token, som Forgejo indsætter (tilgængeligt som FREMFORGE_OIDC_TOKEN i runner-jobbets miljø).

Indsendte JWT’er SKAL have en tenant-specifik aud=https://frem.sh/<slug> og en nylig exp. Det returnerede adgangstoken er en almindelig ffp_-PAT; send den i de efterfølgende kald som Authorization: Bearer <token>. Levetiden er hårdt begrænset til 1 time. Scopes er fællesmængden af forespørgslen og udvekslingens tilladelsesliste; * og tokens:manage kan aldrig tildeles her – brug POST /_app/api/v1/auth/tokens eller administrationsfladen til dem.

# 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

Fra et trin i et Forgejo Actions-workflow ser det samme flow sådan ud:

- 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

Endpointet kræver bevidst ingen godkendelse (JWT’en er godkendelsen), men er begrænset til 30 forsøg i minuttet pr. kilde-IP. Flere forsøg end det returnerer 429 Retry-After. Hver afvist udveksling koster stadig en RSA-verifikation, så en lækket IdP-legitimation eller en CI-løkke, der opfører sig forkert, bliver holdt nede i stedet for at blive forstærket.

Endpoints i faser og agenter, der handler på vegne af brugere

OpenAPI-specifikationen bruger udvidelsen x-fremforge-phase til at markere, om et endpoint er tilgængeligt:

• x-fremforge-phase: 1: i drift og tilgængeligt nu.
• x-fremforge-phase: 2: specificeret, men endnu ikke implementeret; returnerer 501 Not Implemented.

Endpoints uden udvidelsen er fase 1. Et endpoint, der ikke er udgivet, returnerer 501 som RFC 7807 Problem Details, ligesom alle andre fejl i dette API – feltet detail angiver det alternativ, der virker, hvis der findes et:

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

En 501 kan også blot betyde, at stien ikke matchede noget – det samme svar returneres for en ukendt URL, så tjek din sti mod specifikationen, før du konkluderer, at et endpoint ikke er implementeret.

Der findes ingen agentidentiteter. En AI-agent handler på vegne af en person: den kalder dette API med et token, personen har udstedt, med et token fra tokenudveksling efter RFC 8693, der bærer agentens actor_token, eller gennem en MCP-connector, som personen har tilladt. Revisionsloggen registrerer personen som actor og agenten som en detalje (fields.agent, hvor fields.via_token angiver tokenet), og administrationens revisionslog markerer sådanne hændelser med via agent. GET /orgs/{org}/audit?actor= matcher actor, on_behalf_of eller fields.agent præcist, så den finder alt, der er gjort for en person eller af én agent. Se siden om AI-tilgang for, hvad der er i drift, og hvad der er på køreplanen.

Mønstre for brug fra agenter

Tre referencescenarier, som specifikationen er designet ud fra. Har din agent brug for noget, specifikationen ikke understøtter ordentligt, er det et hul, du kan rapportere – skriv til os på support@frem.sh.

Scenarie 1: Oprettelse af en ny organisation ud fra et delegeret mandat

En agent, der handler på vegne af en forhandlers eller administrators mandat, kan oprette en komplet organisation med fire API-kald:

1. POST /orgs: opret organisationen med slug, visningsnavn og faktureringskontakt
2. PUT /orgs/{org}/sso: konfigurér OIDC-SSO for den nye organisation
3. POST /orgs/{org}/seats: angiv det første antal brugere
4. GET /orgs/{org}: bekræft, at organisationen er aktiv, og at SSO er konfigureret

Scenarie 2: Læsning af fund og oprettelse af pull requests med rettelser

Et mandat med kun læseadgang. Agenten poller endpoints for fund, finder punkter med høj alvorlighed og åbner pull requests med rettelser gennem Forgejos almindelige Git-grænseflade (uden for dette REST API; agenten bruger Git over HTTPS eller SSH til den del). Poster i revisionsloggen angiver den person, agenten handler for, med agenten i fields.agent og et via agent-mærke i administrationens revisionslog.

Scenarie 3: Justering af runtime-politik under en hændelse

Et snævert og tidsbegrænset mandat (policy:write:scope=findings-only, gyldigt i 1 time). Agenten anvender en strengere politik (f.eks. blokering af merge ved CRITICAL CVE’er på tværs af alle repositorier), ændringen logges i revisionsloggen med personen som actor og agenten som en detalje i hændelsen, og organisationens ejere ser den i revisionsloggen, når de filtrerer på en af dem.

Versionspolitik

• Major-versioner står i stien (/v1/..., /v2/...). Ændringer, der bryder kompatibiliteten, udgives i en ny major-version med mindst 12 måneders overlap, hvor begge versioner understøttes.
• Minor- og patch-versioner står i info.version. Nye endpoints, nye valgfrie felter og forbedringer af dokumentationen kommer inden for den nuværende major-version uden at bryde kompatibiliteten.
• OpenAPI-specifikationen er den autoritative kilde; afviger en adfærd fra specifikationen, er det specifikationen, der er korrekt, og implementeringen bliver rettet. Rapportér afvigelser til support@frem.sh.

Hastighedsgrænser

API-forespørgsler er hastighedsbegrænset pr. token:

Overskrides en grænse, returneres HTTP 429 med en Retry-After-header, der angiver, hvornår vinduet nulstilles. Grænserne gælder pr. token, ikke pr. IP. Organisationers API-tokens og PAT’er deler de samme grænser pr. token.

Alle svar indeholder også IETF-headerne RateLimit og RateLimit-Policy efter draft-ietf-httpapi-ratelimit-headers. Både grænser pr. token og grænser pr. organisation gælder; den strengeste af de to angives i svarets headers.

Validér specifikationen lokalt

Download specifikationen, og kør så en linter mod den lokale fil:

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

Specifikationen validerer uden fejl mod begge linters; det er et løfte, der skulle være opfyldt før lanceringen af fase 1.

Sikkerhedsfund

Alle scannere, der kan blokere en merge – statisk analyse, afhængigheder, container-images, licenser – udstiller deres fund, så de kan listes og afvises:

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} er en af sast, deps, images, licenses. De svarer ikke til navnene på commit-statusserne, du ser på en pull request (fremforge/sast, fremforge/dep-scan, fremforge/image-scan, fremforge/license-scan) – at udlede stien af statusnavnet er den hyppigste måde at få en 501 på.

To ting mere er værd at vide, før du scripter mod dem. Fund forsvinder ikke ved merge – de forsvinder, når en senere scanning af samme mål ikke længere rapporterer dem, hvorefter et job, der kører hver time, lukker dem som dismissed_by: auto-resolve; afvis eksplicit, når du accepterer et fund, eller når der ikke forventes flere scanninger af det mål. Og licenses tilbyder kun afvisning af ét fund ad gangen, uden et endpoint til masseafvisning.

De fulde skemaer for forespørgsler og svar står i specifikationen. Se API til fund for gennemgåede curl-eksempler.

Registerlegitimationer

Din organisations egne legitimationer med kun læseadgang til private container-registre (kind: oci) og private værter for Git-moduler (kind: git). fremforges scannere bruger dem til at tjekke cosign-signaturer, scanne images og hente Bicep br:- og Terraform-moduler. Din CI ser dem aldrig. Når siden for image-scanning siger, at en registerlegitimation er udløbet eller blev afvist, erstatter en ejer den her eller i konsollen under Sikkerhed › Adgang › Registerlegitimationer, som gør det samme med de samme regler og revisionshændelser. Legitimationer til afhængighedsproxyens egne upstreams (Docker Hub, ghcr.io, quay.io, Red Hats registre) er adskilte: en ejer håndterer dem under Afhængighedsproxy › Upstream-legitimationsoplysninger.

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)

• Kun for organisationens ejere. Brug et API-token for organisationen med policy:read til at liste og policy:write til at ændre.
• Hemmeligheden kan kun skrives. Den er krypteret i hvile og returneres aldrig. En listet legitimation viser fingerprint, expires_at, last_used_at og last_result (ok, refused, expired, rate_limited).
• Én legitimation pr. vært og type. host er kun værtsnavnet, uden scheme, sti eller port. expires_at er påkrævet og højst 366 dage ude i fremtiden. Derefter bruges legitimationen ikke.
• auth_type er basic (username og password, som kan være et token), bearer (token) eller, kun for oci, dockerconfigjson (kun posten for host gemmes).
• Bruges kun til en scanning af din organisation. Siden 2026-10-23 skal hver læsning, fremforges scannere foretager med en af dine legitimationer, bære en kortlivet billet, der er bundet til en scanning af din organisation; en læsning uden billet afvises. En scanning af en anden organisation kan aldrig bruge den.
• Slå funktionen til først. Mens den er slået fra, bruger scanninger ingen legitimation, og ingen kan tilføjes eller roteres. Du kan stadig slette en. Hver ændring skrives i revisionsloggen, uden hemmeligheden.

List legitimationerne, og erstat så hemmeligheden og udløbet for den, der er udløbet:

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>

Tilføj en til et register, der endnu ikke har nogen, eller slet en:

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 fulde skemaer for forespørgsler og svar står i specifikationen under tagget Registry credentials.

Hvad specifikationen ikke dækker

To flader er bevidst uden for rammerne:

1. Forgejos eget API: endpoints under /api/v1/repos, /api/v1/users, /api/v1/issues, /api/v1/pulls osv. Det er Forgejo/Gitea-API’et, som fremforge udstiller uændret på https://frem.sh/_app/api/v1/.... Hver kørende fremforge-instans serverer også den levende Swagger UI på https://frem.sh/api/swagger (genereret direkte fra den kørende Forgejo, så den altid passer til den udrullede version). Migreringsguiderne henviser direkte til disse endpoints, fordi de er Forgejos standardflade.
2. Payloads fra webhook-leveringer: formen på Forgejos webhook-hændelser er defineret upstream. fremforges administrationsflade lader dig konfigurere webhooks; payloads bruger Forgejos hændelsesbegreber (headeren X-Forgejo-Event, X-Forgejo-Signature med HMAC-SHA256).

OpenAPI-specifikationen dækker fremforges eget kontrolplan: organisationer, brugere, politikker, fund, runners, eksporter, revision og mandater. Alt, hvad der findes, fordi fremforge har lagt det oven på Forgejo, står i denne specifikation.

Håndtering af tokens

Der findes to typer tokens.

Typer af tokens

Tommelfingerregel: brug et API-token for organisationen til alt, der kører i produktion eller CI. Brug en PAT til personligt værktøj og udviklingsarbejde.

Opret et API-token for organisationen

1. Gå til Administration → API-tokens → Opret et nyt token (frem.sh/<org>/_admin/api-tokens).
2. Indtast et beskrivende navn (f.eks. ci-deploy, renovate-bot).
3. Vælg scopes. Tilgængelige scopes:

4. Angiv et udløb. Standardlevetiden (når ttl_days udelades) er 90 dage, hvilket også er det maksimale – ttl_days accepterer 1-90. (Siden sagde tidligere 365; API’et afviser alt over 90.) Tokens kan ikke sættes til aldrig at udløbe.
5. Klik på Opret token.

Tokenværdien vises præcis én gang, når tokenet oprettes. Kopiér den, og gem den med det samme i din secret manager. fremforge gemmer ikke selve værdien; serveren beholder kun dens hash. Mister du værdien, så tilbagekald tokenet, og opret et nyt.

Opret en PAT

1. Gå til Brugerindstillinger → Git-adgangstokens → Opret en ny PAT (frem.sh/user/settings#ff-git-pats).
2. Indtast et navn, vælg scopes, og angiv et udløb (standard 90 dage; højst 365 dage).
3. Klik på Opret PAT.

PAT’er bruger samme scope-model som organisationers API-tokens. En PAT arver adgangen fra den bruger, der oprettede den, yderligere begrænset af de valgte scopes.

Isolering af tokens

Organisationers API-tokens er strengt begrænset til én organisation. Et token oprettet under organisationen acme kan ikke få adgang til nogen ressource i organisationen beta, heller ikke selv om den bruger, der oprettede tokenet, er medlem af begge. Det er en grænse, som platformen håndhæver, ikke et tilladelsestjek, der kan omgås.

Det betyder, at du skal bruge ét API-token pr. organisation til automatisering på tværs af flere organisationer. Der findes ingen tokentype på tværs af organisationer.

Rotér et token

Rotér tokens, når de nærmer sig deres udløb, når et teammedlem, der kendte værdien, stopper, eller når et token kan være blevet eksponeret.

Fremgangsmåde for rotation:

1. Opret det nye token under Administration → API-tokens → Opret et nyt token.
2. Opdatér alle, der bruger det gamle token: CI-secrets, udrulningskonfigurationer, .env-filer og tredjepartsintegrationer.
3. Bekræft, at det nye token virker hele vejen igennem, ved at starte en testkørsel eller foretage et test-API-kald.
4. Tilbagekald det gamle token under Administration → API-tokens → find tokenet → Tilbagekald.

Opret først, opdatér brugerne, og tilbagekald så. Tilbagekald aldrig, før erstatningen er på plads.

Tilbagekald et token

1. Gå til Administration → API-tokens (for organisationers API-tokens) eller Brugerindstillinger → Git-adgangstokens (for PAT’er).
2. Find tokenet ud fra navnet.
3. Klik på Tilbagekald.

Tilbagekaldelsen sker med det samme. Enhver forespørgsel med det tilbagekaldte token får svaret 401 Unauthorized. Der er ingen henstandsperiode.

List aktive tokens

Administration → API-tokens viser alle organisationens API-tokens med:

• Tokenets navn
• Brugernavnet på den, der oprettede det
• Oprettelsesdato
• Dato for seneste brug
• Udløbsdato
• Scopes

Tokenværdier er ikke synlige efter oprettelsen. Organisationens ejere kan se metadata for alle tokens, uanset hvilken ejer der oprettede dem. Kun den, der oprettede tokenet, så værdien, da det blev oprettet.

For PAT’er kan hver bruger se sine egne tokens under Brugerindstillinger → Git-adgangstokens. Organisationens ejere kan ikke liste en anden brugers PAT’er, men et fjernet medlems PAT’er mister automatisk adgangen til organisationens ressourcer i det øjeblik, medlemmet fjernes fra organisationen.

Udløb af tokens

Tokens udløber automatisk ved deres konfigurerede levetid. Et udløbet token returnerer 401 Unauthorized. Udløbne tokens kan ikke forlænges. Opret et nyt token, og opdatér dem, der bruger det; slet derefter eventuelt det udløbne token fra listen.

For at undgå nedbrud på grund af et udløb, ingen lagde mærke til, kan du sætte en alarm op i dit overvågningssystem ud fra udløbsdatoen i tokenlisten eller stole på den mail, fremforge sender 7 dage før et API-token for organisationen udløber (sendes til organisationens ejere).

God sikkerhedspraksis

• Gem tokens som krypterede CI-secrets, ikke i filer i repositoriet, i workflow-YAML eller i commit-historikken.
• Brug det mindste sæt scopes, opgaven kræver. Et token, der kun læser repositorier, har ikke brug for orgs:write.
• Sæt den korteste levetid, der er praktisk i driften. Standarden er 90 dage, hvilket også er det maksimale for en organisations API-token.
• Rotér tokens, der kan være blevet eksponeret, i stedet for at gå ud fra, at de ikke er blevet brugt.
• Gennemgå jævnligt, hvornår tokens sidst blev brugt. Et token, der ikke er brugt i 30 dage, kan være en forældet legitimation fra en integration, der er taget ud af drift.

Få hjælp

Spørgsmål om API’ets adfærd, manglende endpoints eller forslag til nye operationer: support@frem.sh med en emnelinje, der starter med API -.