Publikt REST-API

Varje åtgärd i fremforges administrationsgränssnitt har en motsvarighet i det publika REST-API:t. Administrationsgränssnittet är självt en klient till det här API:t, och AI-agenter som agerar för användares räkning använder samma endpoints. Det finns inga endpoints som bara administratörer har och inga oväntade luckor.

Hämta specifikationen

Den kanoniska maskinläsbara specifikationen är OpenAPI 3.1.

• YAML: /api/openapi.yaml, kanonisk, i en enda fil och nedladdningsbar för verktyg.
• JSON-spegel: publiceras på /api/openapi.json vid lansering från samma källa, för klienter som föredrar JSON.

Båda filerna versionshanteras tillsammans med API:t och uppdateras vid varje release av fremforge. OpenAPI-fältet för version följer MAJOR.MINOR.PATCH; själva API:t versionshanteras i sökvägen (/api/v1/...) för bakåtinkompatibla ändringar.

Autentisering

Tre sätt att autentisera, deklarerade i specifikationen som separata securitySchemes så att den som anropar kan välja rätt.

Personliga åtkomsttokens (PAT), för personer och CI-integrationer

Personliga åtkomsttokens hör till en användare, inte till en organisation, så de finns under dina användarinställningar i Forgejo: gå till /<your-user>/settings/applications i Forgejos gränssnitt (till exempel frem.sh/<your-user>/settings/applications). En token har ett namn, en uppsättning scopes och en livslängd på upp till 365 dagar, begränsad av organisationens tak Max PAT lifetime om din administratör har satt ett via Autentiseringspolicy. Själva token visas en gång; servern lagrar bara dess hash.

De skiljer sig från organisationens API-tokens (beskrivs nedan under Hantering av tokens), som finns i fremforges administration på /<org>/_admin/api-tokens och överlever att enskilda medlemmar slutar. Använd en PAT för personliga skript och lokal utveckling; använd en API-token för organisationen för CI och automatisering i produktion.

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

OAuth 2.0 client credentials, för maskin-till-maskin

Standardflödet client credentials enligt RFC 6749. Registrera en klient på organisationsnivå och byt client_id + client_secret mot en token hos token-endpointen:

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-tokenutbyte, för IdP:er och workflow-runners

När din IdP kan utfärda OIDC-JWT:er (Authentik, Entra, Okta, Keycloak, …) eller när ett Forgejo Actions-workflow i fremforge behöver anropa API:t, ska du hellre använda POST /_app/api/v1/auth/token-exchange än långlivade PAT:er. Ingen delad hemlighet lämnar din miljö, och IdP:n roterar den underliggande nyckeln enligt sitt eget schema.

Godkända utfärdare:

• Kundens IdP, registrerad som en auth_sources-post för mål-tenanten (samma JWKS som redan används när medlemmar loggar in). Koppla först in din IdP från tenantens sida med SSO-inställningar.
• fremforges runner-OIDC: steg på Forgejo Actions-runners kan själva skapa en fremforge-token utan någon extra IdP-koppling. Använd den vanliga runner-OIDC-token som Forgejo injicerar (tillgänglig som FREMFORGE_OIDC_TOKEN i runner-jobbets miljö).

Inskickade JWT:er MÅSTE ha en aud=https://frem.sh/<slug> per tenant och en färsk exp. Den access-token som returneras är en vanlig ffp_-PAT; skicka den i efterföljande anrop som Authorization: Bearer <token>. Livslängden är hårt begränsad till 1 timme. Scopen är snittet av begäran och utbytets tillåtlista; * och tokens:manage kan aldrig beviljas här. För dem använder du POST /_app/api/v1/auth/tokens eller administrationsgränssnittet.

# 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

Från ett steg i ett Forgejo Actions-workflow ser samma flöde ut så här:

- 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

Endpointen är oautentiserad med avsikt (JWT:n är autentiseringen) men har en hastighetsgräns på 30 försök per minut och käll-IP. Toppar över det returnerar 429 Retry-After. Varje avvisat utbyte kostar ändå en RSA-verifiering, så en läckande IdP-autentiseringsuppgift eller en CI-loop som beter sig fel begränsas i stället för att förstärkas.

Endpoints i faser och agenter som agerar för användares räkning

OpenAPI-specifikationen använder tillägget x-fremforge-phase för att ange om en endpoint är tillgänglig:

• x-fremforge-phase: 1: i drift och tillgänglig nu.
• x-fremforge-phase: 2: specificerad men inte implementerad än; returnerar 501 Not Implemented.

Endpoints utan tillägget hör till fas 1. En endpoint som inte har levererats returnerar 501 som RFC 7807 Problem Details, precis som alla andra fel i det här API:t. Fältet detail anger det fungerande alternativet när det finns ett:

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

En 501 kan också helt enkelt betyda att sökvägen inte matchade något: samma svar returneras för en okänd URL, så jämför din sökväg med specifikationen innan du drar slutsatsen att en endpoint inte är implementerad.

Det finns inga agentidentiteter. En AI-agent agerar för en persons räkning: den anropar API:t med en token som personen har utfärdat, med en token från RFC 8693-tokenutbyte som bär agentens actor_token, eller via en MCP-anslutning som personen har godkänt. Granskningsloggen registrerar personen som actor och agenten som en detalj (fields.agent, där fields.via_token namnger token), och organisationens granskningslogg markerar sådana händelser med via agent. GET /orgs/{org}/audit?actor= matchar exakt mot aktören, on_behalf_of eller fields.agent, så det hittar allt som gjorts för en person eller av en agent. Se sidan AI-hållning för vad som är i drift och vad som finns på färdplanen.

Mönster för agentanvändning

Tre referensscenarier som specifikationen är utformad kring. Om din agent behöver något som specifikationen inte stöder på ett rent sätt är det en lucka som ska rapporteras: hör av dig till support@frem.sh.

Scenario 1: Skapa en ny organisation utifrån ett delegerat mandat

En agent som agerar utifrån ett mandat från en återförsäljare eller administratör kan skapa en komplett organisation med fyra API-anrop:

1. POST /orgs: skapa organisationen med slug, visningsnamn och faktureringskontakt
2. PUT /orgs/{org}/sso: konfigurera OIDC-SSO för den nya organisationen
3. POST /orgs/{org}/seats: lägg upp det första antalet användare
4. GET /orgs/{org}: kontrollera att organisationen är aktiv och att SSO är konfigurerat

Scenario 2: Läsa fynd och skapa pull requests som åtgärdar dem

Ett mandat med läsbehörighet. Agenten frågar regelbundet fynd-endpointsen, identifierar fynd med hög allvarlighetsgrad och öppnar pull requests som åtgärdar dem via Forgejos vanliga Git-gränssnitt (utanför det här REST-API:ts omfång; agenten använder Git över HTTPS eller SSH för den delen). Poster i granskningsloggen namnger personen som agenten agerar för, med agenten i fields.agent och en via agent-etikett i organisationens granskningslogg.

Scenario 3: Justera policyn under en incident

Ett snävt och tidsbegränsat mandat (policy:write:scope=findings-only, giltigt i 1 h). Agenten tillämpar en striktare policy (till exempel blockerad merge vid CRITICAL-CVE:er i alla repon), ändringen loggas i granskningsloggen med personen som aktör och agenten som en detalj i händelsen, och organisationens ägare ser den i granskningsloggen när de filtrerar på någon av dem.

Versionspolicy

• Huvudversioner i sökvägen (/v1/..., /v2/...). Bakåtinkompatibla ändringar levereras i en ny huvudversion med minst 12 månaders överlapp, då båda versionerna stöds.
• Minor- och patch-versioner i info.version. Nya endpoints, nya valfria fält och förbättrad dokumentation tillkommer inom den nuvarande huvudversionen utan att bryta kompatibiliteten.
• OpenAPI-specifikationen är sanningskällan; om ett beteende skiljer sig från specifikationen är det specifikationen som gäller och implementationen som rättas. Rapportera avvikelser till support@frem.sh.

Hastighetsgränser

API-anrop har hastighetsgränser per token:

När en gräns överskrids returneras HTTP 429 med en Retry-After-header som anger när fönstret återställs. Gränserna gäller per token, inte per IP. Organisationens API-tokens och PAT:er har samma gränser per token.

Varje svar innehåller också IETF-headrarna RateLimit och RateLimit-Policy enligt draft-ietf-httpapi-ratelimit-headers. Både gränser per token och gränser per organisation gäller; den strängaste av dem anges i svarsheadrarna.

Validera specifikationen lokalt

Ladda ned specifikationen och kör sedan en linter mot den lokala 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

Specifikationen validerar utan anmärkningar mot båda lintrarna, ett åtagande som var ett krav för lanseringen av fas 1.

Säkerhetsfynd

Varje skanner som kan blockera en merge (statisk analys, beroenden, container-images, licenser) exponerar sina fynd för listning och avfärdande:

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} är en av sast, deps, images, licenses. De stämmer inte överens med namnen på commit-statusarna som du ser på en pull request (fremforge/sast, fremforge/dep-scan, fremforge/image-scan, fremforge/license-scan); att härleda sökvägen från statusnamnet är det vanligaste sättet att få en 501.

Två saker till är bra att känna till innan du skriptar mot dem. Fynd försvinner inte vid merge; de försvinner när en senare skanning av samma mål inte längre rapporterar dem, och ett jobb som körs varje timme löser dem då som dismissed_by: auto-resolve. Avfärda uttryckligen när du accepterar ett fynd, eller när ingen ytterligare skanning av målet väntas. Och licenses erbjuder bara avfärdande ett i taget, utan endpoint för massavfärdande.

De fullständiga scheman för begäran och svar finns i specifikationen. För genomarbetade curl-exempel, se Fynd-API.

Registerinloggningar

Din organisations egna skrivskyddade inloggningsuppgifter för privata container-register (kind: oci) och privata värdar för Git-moduler (kind: git). fremforges skannrar använder dem för att kontrollera cosign-signaturer, skanna images och hämta Bicep-br:-moduler och Terraform-moduler. Din CI ser dem aldrig. När sidan för image-skanning säger att en registerinloggning har gått ut eller avvisats, ersätter en ägare den här eller i konsolen under Säkerhet › Åtkomst › Registerinloggningar, som gör samma sak med samma regler och granskningshändelser. Inloggningsuppgifter för beroendeproxyns egna upstreams (Docker Hub, ghcr.io, quay.io, Red Hats register) är separata: en ägare hanterar dem under Beroendeproxy › Inloggningsuppgifter för 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)

• Bara organisationens ägare. Använd en API-token för organisationen med policy:read för att lista och policy:write för att ändra.
• Hemligheten kan bara skrivas. Den krypteras i vila och returneras aldrig. En listad inloggningsuppgift visar fingerprint, expires_at, last_used_at och last_result (ok, refused, expired, rate_limited).
• En inloggningsuppgift per värd och typ. host är bara värdnamnet, utan schema, sökväg eller port. expires_at krävs och får ligga högst 366 dagar fram i tiden. Efter det används inloggningsuppgiften inte.
• auth_type är basic (username och password, som kan vara en token), bearer (token) eller, bara för oci, dockerconfigjson (bara posten för host sparas).
• Används bara för en skanning av din organisation. Sedan 2026-10-23 måste varje läsning som fremforges skannrar gör med en av dina inloggningsuppgifter bära en kortlivad biljett som är bunden till en skanning av din organisation; en läsning utan biljett avvisas. En skanning av en annan organisation kan aldrig använda den.
• Slå på funktionen först. Så länge den är avstängd använder skanningar ingen inloggningsuppgift, och ingen kan läggas till eller roteras. Du kan fortfarande ta bort en. Varje ändring skrivs till granskningsloggen, utan hemligheten.

Lista inloggningsuppgifterna och ersätt sedan hemligheten och utgångsdatumet för den som har gått ut:

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>

Lägg till en för ett register som inte har någon än, eller ta bort 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 fullständiga scheman för begäran och svar finns i specifikationen, under taggen Registry credentials.

Vad specifikationen inte täcker

Två ytor ligger avsiktligt utanför omfånget:

1. Forgejos inbyggda API: endpoints under /api/v1/repos, /api/v1/users, /api/v1/issues, /api/v1/pulls osv. Det är Forgejos/Giteas API-yta, som fremforge exponerar oförändrad på https://frem.sh/_app/api/v1/.... Varje körande fremforge-instans serverar också det levande Swagger-gränssnittet på https://frem.sh/api/swagger (renderat direkt från den körande Forgejo, så det är alltid i takt med den driftsatta versionen). Migreringsguiderna hänvisar direkt till de här endpointsen eftersom de är Forgejos standardyta.
2. Innehållet i webhook-leveranser: formen på Forgejos webhook-händelser definieras upstream. I fremforges administrationsgränssnitt konfigurerar du webhooks; innehållet använder Forgejos händelsevokabulär (headern X-Forgejo-Event, X-Forgejo-Signature med HMAC-SHA256).

OpenAPI-specifikationen täcker fremforges eget kontrollplan: organisationer, användare, policy, fynd, runners, exporter, granskning och mandat. Allt som finns för att fremforge har lagt till det ovanpå Forgejo ingår i den här specifikationen.

Hantering av tokens

Det finns två typer av tokens.

Typer av tokens

Tumregel: använd en API-token för organisationen för allt som körs i produktion eller CI. Använd en PAT för personliga verktyg och utvecklingsflöden.

Skapa en API-token för organisationen

1. Gå till Organisationens administration → API-token → Skapa en ny token (frem.sh/<org>/_admin/api-tokens).
2. Ange ett beskrivande namn (till exempel ci-deploy, renovate-bot).
3. Välj scopes. Tillgängliga scopes:

4. Ange ett utgångsdatum. Standardlivslängden (när ttl_days utelämnas) är 90 dagar, vilket också är max: ttl_days tar emot 1–90. (Den här sidan angav tidigare 365; API:t avvisar allt över 90.) Tokens kan inte ställas in så att de aldrig går ut.
5. Klicka på Skapa token.

Tokenvärdet visas exakt en gång när det skapas. Kopiera det och lagra det direkt i din hemlighetshanterare. fremforge lagrar inte själva värdet; servern behåller bara dess hash. Om du tappar bort värdet återkallar du token och skapar en ny.

Skapa en PAT

1. Gå till Användarinställningar → Git-åtkomsttoken → Skapa ett nytt PAT (frem.sh/user/settings#ff-git-pats).
2. Ange ett namn, välj scopes och ange ett utgångsdatum (standard 90 dagar; högst 365 dagar).
3. Klicka på Skapa PAT.

PAT:er använder samma scopemodell som organisationens API-tokens. En PAT ärver åtkomsten hos användaren som skapade den, ytterligare begränsad av de valda scopen.

Isolering av tokens

Organisationens API-tokens är strikt bundna till organisationen. En token som skapats under organisationen acme kan inte komma åt någon resurs i organisationen beta, även om användaren som skapade token är medlem i båda. Det är en gräns som plattformen upprätthåller, inte en behörighetskontroll som går att kringgå.

Det betyder att du behöver en API-token per organisation för automatisering som omfattar flera organisationer. Det finns ingen tokentyp som gäller över organisationer.

Rotera en token

Rotera tokens när de närmar sig sitt utgångsdatum, när en teammedlem som kände till värdet slutar, eller när en token kan ha exponerats.

Så roterar du:

1. Skapa den nya token under Organisationens administration → API-token → Skapa en ny token.
2. Uppdatera alla som använder den gamla token: CI-hemligheter, driftsättningskonfigurationer, .env-filer och tredjepartsintegrationer.
3. Kontrollera att den nya token fungerar hela vägen genom att starta en testkörning eller göra ett test-anrop mot API:t.
4. Återkalla den gamla token under Organisationens administration → API-token → leta upp token → Återkalla.

Skapa först, uppdatera användarna och återkalla sedan. Återkalla aldrig innan ersättaren är på plats.

Återkalla en token

1. Gå till Organisationens administration → API-token (för organisationens API-tokens) eller Användarinställningar → Git-åtkomsttoken (för PAT:er).
2. Leta upp token efter namn.
3. Klicka på Återkalla.

Återkallelsen gäller omedelbart. Varje anrop som använder den återkallade token får svaret 401 Unauthorized. Det finns ingen övergångsperiod.

Lista aktiva tokens

Organisationens administration → API-token visar alla organisationens API-tokens med:

• Tokennamn
• Användarnamn för den som skapade den
• Datum då den skapades
• Datum då den senast användes
• Utgångsdatum
• Scopes

Tokenvärden syns inte efter att de skapats. Organisationens ägare kan se alla tokens metadata oavsett vilken ägare som skapade token. Bara den som skapade token såg värdet när den skapades.

För PAT:er kan varje användare lista sina egna tokens under Användarinställningar → Git-åtkomsttoken. Organisationens ägare kan inte räkna upp en annan användares PAT:er, men en borttagen medlems PAT:er förlorar automatiskt åtkomsten till organisationens resurser i samma ögonblick som medlemmen tas bort från organisationen.

Utgångsdatum för tokens

Tokens går ut automatiskt när den konfigurerade livslängden är slut. En token som har gått ut returnerar 401 Unauthorized. Tokens som har gått ut kan inte förnyas. Skapa en ny token och uppdatera dem som använder den; ta sedan gärna bort den utgångna token från listan.

För att undvika avbrott när en token tyst går ut kan du sätta upp ett larm i ditt övervakningssystem utifrån utgångsdatumet i tokenlistan, eller förlita dig på e-postaviseringen som fremforge skickar 7 dagar innan en API-token för organisationen går ut (skickas till organisationens ägare).

Säkerhetsrutiner

• Lagra tokens som krypterade CI-hemligheter, inte i filer i repot, i workflow-YAML eller i commit-historiken.
• Använd den minsta uppsättning scopes som uppgiften kräver. En token som bara läser repon behöver inte orgs:write.
• Sätt den kortaste livslängd som fungerar i praktiken. Standard är 90 dagar, vilket också är max för en API-token för organisationen.
• Rotera tokens som kan ha exponerats, i stället för att anta att de inte har använts.
• Granska regelbundet när tokens senast användes. En token som inte har använts på 30 dagar kan vara en kvarglömd inloggningsuppgift från en avvecklad integration.

Få hjälp

Frågor om API:ts beteende, saknade endpoints eller förslag på nya operationer: support@frem.sh med en ämnesrad som börjar med API -.