Offentlig REST-API

Hver handling i fremforges admin-UI har en tilsvarende handling i det offentlige REST-API-et. Admin-UI-et er selv en klient av denne flaten, og AI-agenter som handler på vegne av brukere, bruker de samme endepunktene. Det finnes ingen endepunkter bare for admin-UI-et og ingen overraskende hull.

Hent spesifikasjonen

Den kanoniske maskinlesbare spesifikasjonen er OpenAPI 3.1.

• YAML: /api/openapi.yaml, kanonisk, én fil, kan lastes ned til verktøy.
• JSON-speil: publiseres på /api/openapi.json ved lansering fra samme kilde, for klienter som foretrekker JSON.

Begge filene versjoneres sammen med API-et og oppdateres ved hver fremforge-utgivelse. Versjonsfeltet i OpenAPI følger MAJOR.MINOR.PATCH; selve API-et versjoneres i stien (/api/v1/...) for endringer som bryter kompatibiliteten.

Autentisering

Tre autentiseringsveier, deklarert i spesifikasjonen som separate securitySchemes, slik at klientene kan velge den riktige.

Personlige tilgangstokener (PAT), for menneskelige brukere og CI-integrasjoner

Personlige tilgangstokener er knyttet til brukeren, ikke til organisasjonen, så de ligger under brukerinnstillingene dine i Forgejo: gå til /<your-user>/settings/applications i Forgejo-UI-et (f.eks. frem.sh/<your-user>/settings/applications). Tokenene har et navn, et sett med scopes og en levetid på opptil 365 dager, begrenset av taket Max PAT lifetime for hele organisasjonen hvis administratoren din har satt et via Autentiseringspolicy. Selve tokenet vises én gang; bare hashen lagres på serveren.

De er noe annet enn organisasjonens API-tokener (omtalt nedenfor under Håndtering av tokener), som ligger i fremforges administrasjon på /<org>/_admin/api-tokens og overlever at enkeltmedlemmer slutter. Bruk et PAT til personlige skript og lokal utvikling; bruk et API-token for organisasjonen til CI og automatisering i produksjon.

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

OAuth 2.0 client credentials, for maskin-til-maskin

Standard client credentials-tildeling etter RFC 6749. Registrer en klient på organisasjonsnivå, og bytt client_id + client_secret på token-endepunktet:

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"

Bytte av OIDC-token, for IdP-er og workflow-runnere

Når IdP-en din kan utstede OIDC-JWT-er (Authentik, Entra, Okta, Keycloak, …), eller når en Forgejo Actions-workflow i fremforge må kalle tilbake til API-et, bør du bruke POST /_app/api/v1/auth/token-exchange i stedet for langlivede PAT-er. Ingen delt hemmelighet forlater grensen din, og IdP-en roterer den underliggende nøkkelen etter sin egen plan.

Godtatte utstedere:

• Kundens IdP, registrert som en oppføring i auth_sources for måltenanten (den samme JWKS som allerede brukes til innlogging for medlemmer). Koble til IdP-en din fra siden med SSO-innstillinger for kunden først.
• fremforges runner-OIDC: steg i Forgejo Actions-runnere kan selv utstede et fremforge-token uten ekstra oppsett mot en IdP. Bruk det vanlige runner-OIDC-tokenet som Forgejo setter inn (tilgjengelig som FREMFORGE_OIDC_TOKEN i jobbmiljøet til runneren).

JWT-er som sendes inn, MÅ ha en aud=https://frem.sh/<slug> per tenant og en fersk exp. Tilgangstokenet som returneres, er et vanlig ffp_-PAT; send det i senere kall som Authorization: Bearer <token>. Levetiden er absolutt begrenset til 1 time. Scopene er snittet av forespørselen og tillatelseslisten for bytte; * og tokens:manage kan aldri tildeles her – for dem bruker du POST /_app/api/v1/auth/tokens eller admin-UI-et.

# 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 steg i en Forgejo Actions-workflow ser den samme flyten slik ut:

- 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

Endepunktet krever med vilje ingen autentisering (JWT-en er autentiseringen), men er begrenset til 30 forsøk/minutt per kilde-IP. Topper ut over det returnerer 429 Retry-After. Hvert avvist bytte koster likevel en RSA-verifisering, så en IdP-legitimasjon på avveie eller en CI-løkke som oppfører seg feil, blir holdt i sjakk i stedet for å forsterkes.

Endepunkter i faser og agenter som handler på vegne av brukere

OpenAPI-spesifikasjonen bruker utvidelsen x-fremforge-phase til å markere om et endepunkt er tilgjengelig:

• x-fremforge-phase: 1, i drift og tilgjengelig nå.
• x-fremforge-phase: 2, spesifisert, men ikke implementert ennå; returnerer 501 Not Implemented.

Endepunkter uten utvidelsen er fase 1. Et endepunkt som ikke er levert ennå, returnerer 501 som RFC 7807 Problem Details, som alle andre feil i dette API-et – feltet detail nevner alternativet som fungerer, der det finnes 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å ganske enkelt bety at stien ikke traff noe – det samme svaret returneres for en URL som ikke gjenkjennes, så sjekk stien din mot spesifikasjonen før du konkluderer med at et endepunkt ikke er implementert.

Det finnes ingen agentidentiteter. En AI-agent handler på vegne av en person: den kaller dette API-et med et token personen har utstedt, med et token fra token exchange etter RFC 8693 som bærer agentens actor_token, eller via en MCP-connector som personen har tillatt. Revisjonsloggen registrerer personen som actor og agenten som en detalj (fields.agent, der fields.via_token navngir tokenet), og revisjonsloggen i administrasjonen merker slike hendelser med via agent. GET /orgs/{org}/audit?actor= treffer aktøren, on_behalf_of eller fields.agent eksakt, så du finner alt som er gjort for en person eller av én agent. Se siden om AI-holdning for hva som er i drift, og hva som står på veikartet.

Mønstre for bruk fra agenter

Tre referansescenarioer som spesifikasjonen er utformet rundt. Hvis agenten din trenger noe spesifikasjonen ikke støtter på en ryddig måte, er det et hull du kan melde; si fra til support@frem.sh.

Scenario 1: Provisjonere en ny organisasjon ut fra en delegert fullmakt

En agent som handler med fullmakt fra en forhandler eller administrator, kan provisjonere en komplett organisasjon med fire API-kall:

1. POST /orgs, opprett organisasjonen med slug, visningsnavn og faktureringskontakt
2. PUT /orgs/{org}/sso, konfigurer OIDC-SSO for den nye organisasjonen
3. POST /orgs/{org}/seats, provisjoner det første antallet brukere
4. GET /orgs/{org}, bekreft at organisasjonen er aktiv og at SSO er konfigurert

Scenario 2: Lese funn og opprette pull requests med utbedringer

En fullmakt med bare lesetilgang. Agenten spør endepunktene for funn jevnlig, finner elementer med høy alvorlighetsgrad og åpner pull requests med utbedringer via det vanlige Git-grensesnittet i Forgejo (utenfor dette REST-API-et; agenten bruker Git over HTTPS eller SSH til den delen). Oppføringer i revisjonsloggen navngir personen agenten handler for, med agenten i fields.agent og en via agent-brikke i revisjonsloggen i administrasjonen.

Scenario 3: Justere policy under en hendelse

En snevert avgrenset og tidsbegrenset fullmakt (policy:write:scope=findings-only, gyldig i 1 time). Agenten tar i bruk en strengere policy (f.eks. blokkering av merge ved CRITICAL CVE-er i alle repositoryer), endringen logges i revisjonsloggen med personen som aktør og agenten som en detalj i hendelsen, og eiere av organisasjonen ser den i revisjonsloggen når de filtrerer på en av dem.

Versjoneringspolicy

• Hovedversjoner står i stien (/v1/..., /v2/...). Endringer som bryter kompatibiliteten, kommer i en ny hovedversjon med minst 12 måneders overlapp der begge versjonene støttes.
• Mindre versjoner og patchversjoner står i info.version. Nye endepunkter, nye valgfrie felt og forbedringer av dokumentasjonen kommer innenfor gjeldende hovedversjon uten å bryte kompatibiliteten.
• OpenAPI-spesifikasjonen er fasiten; hvis en oppførsel avviker fra spesifikasjonen, er det spesifikasjonen som er riktig, og implementasjonen blir rettet. Meld avvik til support@frem.sh.

Frekvensgrenser

API-forespørsler har frekvensgrenser per token:

Hvis en grense overskrides, returneres HTTP 429 med en Retry-After-header som sier når vinduet nullstilles. Grensene gjelder per token, ikke per IP. API-tokener for organisasjonen og PAT-er deler de samme grensene per token.

Hvert svar har også IETF-headerne RateLimit og RateLimit-Policy etter draft-ietf-httpapi-ratelimit-headers. Både grensene per token og grensene per organisasjon gjelder; den strengeste av dem rapporteres i svarheaderne.

Validere spesifikasjonen lokalt

Last ned spesifikasjonen, og kjør deretter en linter mot den lokale filen:

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

Spesifikasjonen validerer uten feil mot begge linterne; det er en forpliktelse som må være oppfylt før lanseringen av fase 1.

Sikkerhetsfunn

Hver skanner som kan blokkere en merge – statisk analyse, avhengigheter, containerimager, lisenser – gjør funnene sine tilgjengelige for listing og avvisning:

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 av sast, deps, images, licenses. Disse er ikke de samme som navnene på commit-statusene du ser på en pull request (fremforge/sast, fremforge/dep-scan, fremforge/image-scan, fremforge/license-scan) – å utlede stien fra statusnavnet er den vanligste måten å få en 501 på.

To ting til er verdt å vite før du skriver skript mot dem. Funn forsvinner ikke ved merge – de forsvinner når en senere skanning av det samme målet ikke lenger rapporterer dem, og en jobb som kjører hver time, løser dem da opp som dismissed_by: auto-resolve; avvis eksplisitt når du godtar et funn, eller når det ikke ventes flere skanninger av det målet. Og licenses tilbyr bare avvisning av ett funn om gangen, uten endepunkt for masseavvisning.

De fullstendige skjemaene for forespørsler og svar står i spesifikasjonen. For gjennomarbeidede curl-eksempler, se Findings-API-et.

Registerlegitimasjon

Organisasjonens egen skrivebeskyttede legitimasjon for private containerregistre (kind: oci) og private verter for git-moduler (kind: git). fremforges skannere bruker dem til å sjekke cosign-signaturer, skanne imager og hente Bicep br:- og Terraform-moduler. CI-en din ser dem aldri. Når siden for imageskanning sier at en registerlegitimasjon er expired eller ble refused, erstatter en eier den her eller i konsollen under Sikkerhet › Tilgang › Registerlegitimasjon, som gjør det samme med de samme reglene og revisjonshendelsene. Legitimasjon for avhengighetsproxyens egne upstreams (Docker Hub, ghcr.io, quay.io, Red Hat-registrene) er noe annet: en eier håndterer dem under Avhengighetsproxy › Påloggingsdetaljer for upstream.

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)

• Bare for eiere av organisasjonen. Bruk et API-token for organisasjonen med policy:read for å liste og policy:write for å endre.
• Secreten kan bare skrives. Den er kryptert i lagring og returneres aldri. En legitimasjon i listen viser fingerprint, expires_at, last_used_at og last_result (ok, refused, expired, rate_limited).
• Én legitimasjon per vert og type. host er bare vertsnavnet, uten skjema, sti eller port. expires_at er påkrevd og høyst 366 dager fram i tid. Etter det brukes ikke legitimasjonen.
• auth_type er basic (username og password, som kan være et token), bearer (token) eller, bare for oci, dockerconfigjson (bare oppføringen for host beholdes).
• Brukes bare til skanning av din organisasjon. Siden 2026-10-23 må hver lesing som fremforges skannere gjør med en av legitimasjonene dine, ha med en kortlivet billett som er bundet til en skanning av organisasjonen din; en lesing uten billett avvises. En skanning av en annen organisasjon kan aldri bruke den.
• Slå på funksjonen først. Så lenge den er av, bruker skanningene ingen legitimasjon, og ingen kan legges til eller roteres. Du kan fortsatt slette en. Hver endring skrives til revisjonsloggen, uten secreten.

List legitimasjonene, og erstatt deretter secreten og utløpstiden for den som er utløpt:

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>

Legg til en for et register som ikke har noen ennå, eller slett 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 fullstendige skjemaene for forespørsler og svar står i spesifikasjonen, under taggen Registry credentials.

Hva denne spesifikasjonen ikke dekker

To flater er med vilje utenfor:

1. Forgejos eget API, endepunkter under /api/v1/repos, /api/v1/users, /api/v1/issues, /api/v1/pulls osv. Det er Forgejo/Gitea-API-flaten som fremforge eksponerer uendret på https://frem.sh/_app/api/v1/.... Hver fremforge-instans som kjører, leverer også det levende Swagger-UI-et på https://frem.sh/api/swagger (generert direkte fra Forgejo-instansen som kjører, så det er alltid i takt med versjonen som er rullet ut). Migreringsveiledningene viser direkte til disse endepunktene fordi de er den vanlige Forgejo-flaten.
2. Innholdet i webhook-leveranser: formen på Forgejos webhook-hendelser er definert upstream. Admin-UI-et i fremforge lar deg konfigurere webhooks; innholdet bruker Forgejos hendelsesvokabular (headeren X-Forgejo-Event, X-Forgejo-Signature HMAC-SHA256).

OpenAPI-spesifikasjonen dekker fremforges eget kontrollplan: organisasjoner, brukere, policy, funn, runnere, eksporter, revisjon, fullmakter. Alt som finnes fordi fremforge har lagt det til oppå Forgejo, står i denne spesifikasjonen.

Håndtering av tokener

Det finnes to typer tokener.

Tokentyper

Tommelfingerregel: bruk et API-token for organisasjonen til alt som kjører i produksjon eller CI. Bruk et PAT til personlige verktøy og utviklingsarbeid.

Opprette et API-token for organisasjonen

1. Gå til Organisasjonsadministrasjon → API-tokener → Lag et nytt token (frem.sh/<org>/_admin/api-tokens).
2. Skriv inn et beskrivende navn (f.eks. ci-deploy, renovate-bot).
3. Velg scopes. Tilgjengelige scopes:

4. Angi en utløpstid. Standard levetid (når ttl_days utelates) er 90 dager, som også er maksimum – ttl_days godtar 1–90. (Denne siden sa tidligere 365; API-et avviser alt over 90.) Tokener kan ikke settes til å aldri utløpe.
5. Klikk Lag token.

Tokenverdien vises nøyaktig én gang når tokenet opprettes. Kopier den og lagre den med en gang i secret-håndteringen din. fremforge lagrer ikke selve verdien; bare hashen beholdes på serveren. Hvis du mister verdien, tilbakekaller du tokenet og oppretter et nytt.

Opprette et PAT

1. Gå til Brukerinnstillinger → Git-tilgangstokener → Lag en ny PAT (frem.sh/user/settings#ff-git-pats).
2. Skriv inn et navn, velg scopes og angi en utløpstid (standard 90 dager; maksimum 365 dager).
3. Klikk Lag PAT.

PAT-er bruker den samme scope-modellen som API-tokener for organisasjonen. Et PAT arver tilgangen til brukeren som opprettet det, ytterligere begrenset av scopene som er valgt.

Isolasjon av tokener

API-tokener for organisasjonen er strengt avgrenset til organisasjonen. Et token som er opprettet under organisasjonen acme, har ikke tilgang til noen ressurs i organisasjonen beta, selv om brukeren som opprettet tokenet, er medlem av begge. Dette er en grense plattformen håndhever, ikke en tilgangssjekk som kan omgås.

Det betyr at du trenger ett API-token per organisasjon for automatisering på tvers av flere organisasjoner. Det finnes ingen tokentype på tvers av organisasjoner.

Rotere et token

Roter tokener når de nærmer seg utløp, når et teammedlem som kjente verdien, slutter, eller når et token kan ha blitt eksponert.

Fremgangsmåte for rotasjon:

1. Opprett det nye tokenet under Organisasjonsadministrasjon → API-tokener → Lag et nytt token.
2. Oppdater alle som bruker det gamle tokenet: CI-secrets, utrullingskonfigurasjoner, .env-filer, tredjepartsintegrasjoner.
3. Bekreft at det nye tokenet fungerer hele veien ved å starte en testkjøring eller gjøre et test-kall mot API-et.
4. Tilbakekall det gamle tokenet under Organisasjonsadministrasjon → API-tokener → finn tokenet → Tilbakekall.

Opprett først, oppdater brukerne av tokenet, og tilbakekall deretter. Tilbakekall aldri før erstatningen er tatt i bruk.

Tilbakekalle et token

1. Gå til Organisasjonsadministrasjon → API-tokener (for API-tokener for organisasjonen) eller Brukerinnstillinger → Git-tilgangstokener (for PAT-er).
2. Finn tokenet etter navn.
3. Klikk Tilbakekall.

Tilbakekallingen gjelder umiddelbart. Enhver forespørsel med det tilbakekalte tokenet får svaret 401 Unauthorized. Det finnes ingen frist.

Liste aktive tokener

Organisasjonsadministrasjon → API-tokener viser alle API-tokener for organisasjonen med:

• Tokennavn
• Brukernavnet til den som opprettet tokenet
• Opprettelsesdato
• Dato for siste bruk
• Utløpsdato
• Scopes

Tokenverdier er ikke synlige etter at tokenet er opprettet. Eiere av organisasjonen kan se alle metadata om tokenene, uansett hvilken eier som opprettet tokenet. Bare den som opprettet tokenet, så verdien da det ble opprettet.

For PAT-er kan hver bruker liste sine egne tokener under Brukerinnstillinger → Git-tilgangstokener. Eiere av organisasjonen kan ikke liste en annen brukers PAT-er, men PAT-ene til et medlem som fjernes, mister automatisk tilgangen til organisasjonens ressurser i det øyeblikket medlemmet fjernes fra organisasjonen.

Utløp av tokener

Tokener utløper automatisk når den konfigurerte levetiden er over. Et utløpt token returnerer 401 Unauthorized. Utløpte tokener kan ikke fornyes. Opprett et nytt token og oppdater brukerne av det; slett eventuelt det utløpte tokenet fra listen etterpå.

For å unngå driftsavbrudd fordi et token utløper i det stille, setter du opp et varsel i overvåkingssystemet ditt basert på utløpsdatoen som vises i tokenlisten, eller du stoler på varselet på e-post som fremforge sender 7 dager før et API-token for organisasjonen utløper (sendes til eierne av organisasjonen).

Sikkerhetspraksis

• Lagre tokener som krypterte CI-secrets, ikke i filer i repositoryet, workflow-YAML eller commit-historikken.
• Bruk det minste settet med scopes som oppgaven krever. Et token som bare leser repositoryer, trenger ikke orgs:write.
• Sett den korteste levetiden som er praktisk i drift. Standard er 90 dager, som også er maksimum for et API-token for organisasjonen.
• Roter tokener som kan ha blitt eksponert, i stedet for å anta at de ikke ble brukt.
• Gå jevnlig gjennom datoene for siste bruk av tokenene. Et token som ikke er brukt på 30 dager, kan være en gammel legitimasjon fra en integrasjon som er faset ut.

Få hjelp

Spørsmål om hvordan API-et oppfører seg, manglende endepunkter eller forslag til nye operasjoner: support@frem.sh med en emnelinje som begynner med API -.