List FOSSA projects visible to the current account.

Use this first when the user names a project informally or asks for an organization-wide project inventory. Supports sorting by licensing, security, quality, scan time, and title.

Read-only. A locators filter long enough to overflow a URL is sent to FOSSA's equivalent POST endpoint instead; the result is the same.

Get detailed metadata about exactly one FOSSA project.

Use the exact FOSSA locator returned by another FOSSA MCP tool. Do not guess it from a repository name.

Count the projects, shared projects, and release groups in the organization.

Read-only. Use it for a size check before listing anything; it answers "how many" without paging through fossa_list_projects.

List a project's labels, its release-group memberships, and the timestamp of the last update published for it.

Read-only. Each section is one FOSSA call. By default this fetches "labels" and "release_groups"; name "last_published" in sections to fetch that too. It comes back as a bare ISO timestamp string.

Sections are independent: one failing section does not discard the others. Every section that answered is under data, keyed by section name, and every section FOSSA rejected is under errors with its status code and message. The two keys never overlap, so a section that came back empty (present in data as [] or {}) is distinct from one that failed (absent from data, present in errors). Check errors before concluding a project has no labels or no release groups.

"last_published" is not fetched by default because FOSSA answers it with 404 NotFoundError: Last published date not known for a project that has never had an update published, which is the common case. Treat that particular 404 as "nothing published yet" rather than as a broken call — FOSSA's own message says the date is not known, not that the project or the endpoint is missing. Any other status under errors is a real failure.

Export every issue on a project revision as one JSON or CSV document.

Read-only. This is the whole-project export FOSSA's UI offers, grouped by issue type; use fossa_list_issues instead when the caller wants filtered, paged issues rather than a report. Without revision_id or ref the latest revision on the default branch is exported. CSV is returned as raw text under data.content.

Update one project's settings: metadata, branches, policy assignments, scanning, CI status checks, labels, and ignored dependencies.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Every field defaults to None, meaning "leave unchanged" — only the fields named in the call are sent. Two of them replace rather than merge: label_ids replaces the project's whole label set, and transitive_excludes replaces the whole ignore list, so read the current value with fossa_get_project first if you mean to add to either. tracking_branches and hidden_branches are mutually exclusive.

Changing a policy or a scanning setting makes FOSSA rescan the project.

Apply one existing organization label to a list of projects.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

label_id is a numeric id of a label that already exists in the organization; this does not create labels. Every target project must be named explicitly — the endpoint's "apply to all projects matching these filters" mode is deliberately not exposed. FOSSA answers with a map of the projects that failed, which is reported under failures.

Create or regenerate the slug in the URL of a project's live attribution report.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Regenerating replaces the existing slug, which breaks any previously shared report link. FOSSA requires a Premium subscription for this endpoint and answers 403 without one. The response is the new slug as a bare JSON string.

Remove the slug from a project's live attribution report URL, which takes the shared report offline.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

Anyone holding the old link loses access. Only the slug is deleted; the project and its scan history are untouched.

Permanently delete one project and everything FOSSA has scanned for it.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

This cannot be undone: revisions, issues, and scan history go with the project. Confirm the exact locator with fossa_get_project first; a locator guessed from a repository name may name a different project.

Permanently delete several named projects in one call.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

Every project must be named by locator. FOSSA's endpoint also accepts locators=all, which deletes every project matching a set of filters and, with no filters, every project in the organization; this tool does not expose that mode and no combination of arguments can reach it. Deletion cannot be undone.

List analyzed revisions, branches, or tags for a project.

Use the full revision locator returned by FOSSA, including any $revision suffix.

List the policy scans FOSSA has run against a revision, newest first.

Each entry names the licensing, security, and quality policy versions that were in force for that scan, which is how to tell whether a finding predates a policy change.

Return the NOTICE files FOSSA found in a revision's distributed source.

Set include_contents=False for just the paths and copyright lines. Notice text is capped in total at FOSSA_REPORT_MAX_CHARS across all files, and the files that were cut carry contents_truncated.

Return FOSSA's analysis of an uploaded SBOM, or a link to the original file.

part="analysis" reports what FOSSA made of the document: whether it parsed as an SBOM, which required fields were present, and how the dependency scan went. part="original" asks for the file as uploaded; FOSSA answers that with a redirect, so what comes back is the download URL, not the document.

Both only apply to SBOM projects. Any other project type answers 400.

Return FOSSA's remediation guidance report for a revision.

The report is the ranked fix plan: quick wins, high and low priority work, and outdated dependencies.

Requires a Premium subscription with Security enabled; other organizations get a 403. The endpoint also offers PDF and zip-bundle output, which this tool does not request because neither survives being returned as text.

Return a revision's attribution report as structured JSON.

Prefer this over the rendered formats when the answer will be reasoned about rather than handed to a person. api_version="v1" calls the legacy path, which takes the same options and differs only in response shape.

Requires a Premium subscription; other organizations get a 403. The response shape is not declared in the OpenAPI spec, so it is passed through as FOSSA returns it.

Generate a revision's attribution report and return the rendered document.

variant="stream" is the general report endpoint, "preview" renders it inline, and "full" turns on every report option server-side and therefore accepts no options here. For the plain file download use fossa_get_attribution_report.

PDF is not offered: the document is returned as text and a PDF does not survive that. Output is capped at FOSSA_REPORT_MAX_CHARS.

List a revision's dependencies in FOSSA's legacy v1 response shape.

The v1 shape carries the dependency lock, full license objects, and issue targets, none of which the v2 response includes.

fossa_list_dependencies is the better default; this exists for the fields the v2 response drops and for filtering by a locator list too long for a query string. With transport="auto" a long locator list is sent as a request body instead, which is FOSSA's documented workaround for the URI size limit. Neither transport changes FOSSA state.

Update a revision's metadata: its link, url, or author.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Only the fields you pass are sent; the rest are left as they are. This edits the recorded provenance of an analyzed revision, not its analysis results.

Email a revision's attribution report to the account behind the API token.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

The side effect is an outbound email rather than a change to FOSSA state, which is why it is gated despite being a GET. The response is the queued task, not the report. api_version="v1" calls the legacy path.

Create a publicly reachable link to a revision's attribution report.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

The generated report is readable by anyone holding the URL, with no FOSSA login, so this publishes whatever the selected options include — dependency inventory, licenses, and optionally open vulnerabilities. Requires a Premium subscription. FOSSA answers 202: the record comes back immediately and the document is generated by the returned background task.

List dependencies detected in a specific project revision, with filters useful for licensing/security investigation.

Get the richer detail record for one dependency in one revision.

Use the exact dependency revision locator returned by fossa_list_dependencies.

Query licensing, vulnerability, or quality issues globally or for one project revision. Supports comparing issues between revisions.

Retrieve complete detail for one issue.

Summarize the current issue set one dimension at a time: counts by category, by type, or by status, or the distinct CWEs, licenses, or package managers that issues were found in.

Read-only. Use this before fossa_list_issues to find out what is worth listing. category is required for the license-list, package-managers, and statuses facets and rejected by the others; status applies only to cwes and package-managers.

List issues grouped by the dependency revision that carries them, with per revision issue and project counts.

Read-only. This is the "which packages should we upgrade first" view; fossa_list_issues is the per-issue view of the same data.

Count how many issues are new, remediated, or unchanged between two revisions of one project.

Read-only. Answers "what did this build change" in one call; use fossa_list_issues with compare_to_revision to see the issues themselves.

List the projects and revisions affected by one issue.

Read-only. This is the blast-radius view of a single CVE or policy conflict: which projects carry it, on which branch, and whether a ticket is already filed.

Request the organization-wide issues report as CSV.

Read-only with respect to FOSSA state. With email=true (the default) FOSSA queues the export and mails it to the calling token's user, and this returns the background task metadata. With email=false FOSSA streams a zip archive, which this tool reports on but does not return: the archive is binary and cannot travel over MCP as text.

Requires the Create permission on OrganizationReport or TeamReport.

List the organization's issue ignore rules, or fetch one by id.

Read-only. An exception is what keeps an issue out of the active set: it records the scope it applies to, who created it, and when it expires. Pass exception_id for a single rule, or category to list.

Retrieve daily active, ignored, and remediated issue counts over a date range.

Read-only. This is the trend view behind FOSSA's Issue Overview: how the backlog moved, not what is in it.

List the organization's saved issue filters for one category, or fetch one by id.

Read-only. A saved filter records the criteria, sort, and grouping the FOSSA issue views use; reading one tells you what a team considers its working set.

Ignore, unignore, unlink, or create a reusable exception for a set of issues.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true, and additionally FOSSA_ALLOW_DESTRUCTIVE=true when issue_ids is omitted.

Passing issue_ids acts on exactly those issues. Omitting it acts on every issue matching the filters, a set the caller cannot see in advance, so that form is gated at the destructive tier and requires a project scope or at least one filter. Run fossa_list_issues with the same arguments first to see what will be affected.

The issueException action creates a durable ignore rule rather than a one-off ignore; package_scope, ignore_scope, expires_after, and license_id only apply to it. Ticket export is not offered by this tool.

Change when an issue exception expires, or clear the expiry so it never does.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

expires_after has no default because null is meaningful here: it removes the expiry, leaving the issue ignored indefinitely. Pass a YYYY-MM-DD date to set one. Requires a premium FOSSA subscription.

Delete issue ignore rules, which makes the issues they were suppressing active again.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

Pass exactly one target: exception_id for a single rule, exception_ids for a named list, or a filter (category, project_id, release_group_id, policy_id) to delete every rule matching it. The filter form must name at least one filter, so there is no way to clear an organization's exceptions in one call. Run fossa_get_issue_exceptions first to see what a filter covers.

Dispute a licensing or quality issue, telling FOSSA the finding is wrong.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

The dispute type follows the issue's own category, so the reason must match it: the INCORRECT_DEPENDENCY_VERSION_REPORTED, LICENSE_DETECTION_FALSE_ POSITIVE, MULTI_OR_DUAL_LICENSED, and INCORRECT_LICENSE_CONCLUSION reasons are for licensing issues; INCORRECT_STALENESS_REPORTED, INCORRECTLY_FLAGGED_ ABANDONWARE, and INCORRECTLY_FLAGGED_EMPTY are for quality issues. Vulnerability issues cannot be disputed.

Queue an export of the issues behind the Issue Overview counts.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

This does not change any issue, but it does create a background job in the organization and deliver a report, so it is gated like any other POST. Returns the job token FOSSA uses to track the export; this server has no endpoint to poll it.

Create a saved issue filter for the organization, or update an existing one.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Omit filter_id and pass category to create; pass filter_id to update. A filter's category is fixed at creation. criteria is the filter body FOSSA stores as-is, keyed by the same names the issue views use (severity, packageManagers, projectLabels, search, ticketed, cwes, and so on). Requires a premium FOSSA subscription.

Delete a saved issue filter.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

The filter must belong to the calling token's organization. Deleting it removes it for everyone who uses it.

Get a FOSSA release group by its numeric id, optionally with the teams assigned to it and the projects it contains.

Read-only. release_group_id is the integer in the release group's FOSSA URL. Sections: "group" is the release group record and its releases, "teams" is the assigned teams, "projects" is every project locator in the group across all releases. Defaults to "group" alone.

List the releases in a FOSSA release group, paginated.

Read-only. FOSSA caps count at 50 on this endpoint. search filters by release title. The unpaginated /project_group/{id}/release endpoint is deprecated by FOSSA and is not exposed.

Get one release inside a FOSSA release group, and any of its rolled-up license, obligation, revision, scan, and issue-count views.

Read-only. Sections: "release" is the release and its pinned projects, "summary" is the issue, project, and dependency counts, "licenses" and "obligations" are the license rollups keyed by license id, "revisions" is the revisions in the release, "scans" is the release scan history. Defaults to "release" and "summary". Each section costs one FOSSA request, so ask only for what is needed.

Generate and return an attribution or SBOM report for one release in a FOSSA release group, synchronously.

Read-only. The report is streamed back rather than queued, and the portal publishing switch this endpoint also offers is deliberately not exposed here because publishing is a write; use fossa_queue_release_group_attribution_report for that. PDF is not offered because the response is decoded as text. exclude_package_labels drops every dependency carrying any of the named package labels.

Check whether a queued release group attribution report has finished.

Read-only. task_id is the value returned by fossa_queue_release_group_attribution_report. The response carries a status of CREATED, ASSIGNED, RUNNING, SUCCEEDED, or FAILED, plus a download URL once it has succeeded.

Create a FOSSA release group together with its first release.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

FOSSA has no empty release group, so the first release and its projects are part of the same call. Each entry in projects is an object with the keys projectId (a FOSSA project locator such as git+github.com/acme/widget), and optionally branch and revisionId. The call fails if the organization is already at its release group limit.

Update a FOSSA release group's title, policies, portal visibility, or report text.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Only the fields passed are sent; anything omitted is left as FOSSA has it. Because an omitted argument and an explicit null look the same in a tool call, unsetting a nullable field is a separate list: naming a field in clear_fields sends null for it. Setting and clearing the same field in one call is rejected. This does not touch releases; use fossa_update_release_group_release for those.

Delete a FOSSA release group and every release in it.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

This removes the grouping, not the projects: the projects and their scan history survive. The release group and its releases do not, and FOSSA offers no undo. To remove one release instead, use fossa_delete_release_group_release.

Add a release to an existing FOSSA release group.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Each entry in projects is an object with the keys projectId (a FOSSA project locator), and optionally branch and revisionId. A release with no projects reports nothing, so at least one is required.

Rename a release in a FOSSA release group and add, repin, or remove the projects in it.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

FOSSA requires title on this endpoint even when only the project list is changing; pass the release's current title to leave it as it is. Entries in projects are added or repinned, and each is an object with the keys projectId, and optionally branch and revisionId. projects_to_delete is a list of project locators to drop from the release. Naming the same project in both is rejected.

Delete one release from a FOSSA release group.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

The release group and its other releases are left alone, as are the projects the release pinned. FOSSA offers no undo.

Queue an attribution or SBOM report for one release in a FOSSA release group as a background job, and optionally publish it to the SBOM portal.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

This is gated because it creates a job on FOSSA's side and, with is_publishing set, makes the report visible on the organization's SBOM portal. It returns a task id; poll it with fossa_get_release_group_attribution_status. For a report you just want to read, fossa_get_release_group_attribution_report returns the content directly and writes nothing.

Provide one high-value, model-friendly view of a project revision's current FOSSA issue posture.

This is a composite MCP workflow and is the centerpiece demo tool.

Retrieve a text-friendly FOSSA attribution/SBOM report for a revision.

Show the security policy in force for a project: what FOSSA is configured to enforce, plus the local overlay layered on top of it.

Read-only. The overlay can only make enforcement stricter, never looser.

Evaluate every dependency in a revision against the effective security policy and return an allow/warn/block verdict per package.

Read-only: this reports what the policy says, it does not apply anything to FOSSA. A FOSSA-raised vulnerability always blocks and cannot be cleared by a local exception.

Assign a FOSSA security policy to a project and turn on the enforcement that blocks packages violating it.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Blocking in FOSSA is the combination of an assigned security policy (which decides what counts as a violation), security issue scanning (which finds violations), and the security status check (which fails the build). This tool sets all three. security_policy_id is the numeric id from the policy's FOSSA URL; the API exposes no way to list policies.

Assign one FOSSA security policy to several projects at once.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Assignment only. Unlike fossa_enable_security_policy this does not touch scanning or the status check, because the bulk endpoint cannot set them — a project that has scanning switched off will take the policy and still block nothing.

This tool deliberately does not expose the endpoint's "apply to all projects matching these filters" mode. Every target must be named explicitly, and an empty or all-blank list is refused rather than sent — FOSSA does not enforce the locator list as required, so the resulting request would re-policy every project in the organization.

List the teams in the FOSSA organization.

Read-only. Paginated: FOSSA caps page_size at 50, and search filters by team name. Each result carries the team's default role, its member count, and how many projects and release groups it owns.

Setting include_all_with_members switches to FOSSA's older unpaginated endpoint, which returns every team with its full member list inline. That is the only call that answers "who is in which team" in one request, but FOSSA marks it deprecated and it accepts no paging or search, so it is not the default.

Get a FOSSA team by its numeric id, and any of its member, project, and release group listings.

Read-only. Sections: "team" is the team record and its counts, "members" is the users in it with their team role, "projects" is the project locators assigned to it, "release_groups" is the release groups assigned to it. Defaults to "team" alone. Each section costs one FOSSA request, so ask only for what is needed.

page, page_size, and search apply to the three list sections and are shared across them; sort orders "projects" and "release_groups" by title and is rejected if neither is requested.

List what could still be added to a FOSSA team: the users, projects, and release groups that are not in it yet.

Read-only. Targets: "users" is the organization's users who are not members, "projects_and_release_groups" is everything assignable to the team with a type discriminator on each entry, and "release_group_projects" narrows that to the projects inside one release group — FOSSA requires every project of a release group to be on the team before the release group itself can be added, so that target answers "what is still missing". It takes release_group_id and, unlike the other two, returns the whole set with no paging.

Get FOSSA team groups — every one in the organization, or a single group by its numeric id.

Read-only. A team group is a container that owns teams and carries its own default role; it is not itself a team. Both responses list the group's teams with their project counts and its members with their role ids; asking for one group by id additionally resolves each member's username and email. Neither endpoint is paginated.

List the roles in the FOSSA organization, the permission catalog they are built from, and which of them the calling token may hand out.

Read-only. Sections: "roles" is every role with its scope and permission list, "permissions" is the catalog of (resourceType, action) pairs a custom role can be assembled from, "assignable" is the subset of role ids this API token is allowed to assign — FOSSA only lets a caller grant permissions it already holds, so a role missing from "assignable" will be refused when used in a team or service account write. Defaults to "roles" alone. Each section costs one FOSSA request. None of these endpoints is paginated.

List the users in the FOSSA organization, or fetch one user by numeric id.

Read-only. The default is FOSSA's paginated user list: page_size is capped at 50, search matches username, email, or full name, and sort takes a field_asc / field_desc pair. Passing user_id fetches that single user instead, with their organization role, team memberships, and API token metadata — token names and ids, never token values.

Setting include_all switches to FOSSA's older unpaginated endpoint, which returns every user in one response. FOSSA marks it deprecated and it supports neither search nor sort, so it is not the default.

Service accounts appear in these listings alongside people, flagged by isServiceAccount.

Create a FOSSA team.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

default_role_id is the team role new members receive; list the available ids with fossa_list_roles. auto_add_users puts every new organization user into this team automatically, which widens access without another call, so it defaults to false. unique_identifier is an external key FOSSA stores for SCIM and SSO mapping. team_group_ids places the new team into existing team groups and requires the team groups feature to be enabled.

Update a FOSSA team's name, default role, auto-add setting, or external identifier.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

Only the fields passed are sent; anything omitted is left as FOSSA has it. Because an omitted argument and an explicit null look the same in a tool call, unsetting the nullable uniqueIdentifier is a separate switch: clear_unique_identifier sends null for it. Changing default_role_id affects members added afterwards, not the roles already assigned — use fossa_update_team_assignments with action "replace" to re-role existing members. This tool does not change membership.

Delete a FOSSA team.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true, and FOSSA_ALLOW_DESTRUCTIVE=true.

This removes the team from every team group it belongs to and drops all of its associations: its members lose the access the team granted them, and its projects and release groups lose that team assignment. The users, projects, and release groups themselves survive; the team does not, and FOSSA offers no undo.

Change what is assigned to a FOSSA team: its members, its projects, or its release groups.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true. Any call that can take an assignment away — action "remove" or "replace", or a projects call using all_projects or project_filters — additionally requires FOSSA_ALLOW_DESTRUCTIVE=true. A bounded "add" does not.

target picks the collection and decides which of the remaining arguments apply; passing one that belongs to a different target is rejected before any request is made.

• "users" takes users, a list of objects with the keys id and, for the add and replace actions, roleId.

• "projects" takes exactly one of projects (a list of project locators), all_projects, or project_filters (an object with any of title, labels, type, lastRevisionWithin, isPublic).

• "release_groups" takes release_group_ids, and supports only add and remove. Every project in a release group must already be on the team before the release group can be added.

action "replace" sets the collection to exactly what is named and removes everything else, so replacing the user list with one entry leaves a team of one. all_projects and project_filters address an unbounded set: FOSSA resolves them server-side, so the number of projects affected is not known before the call. all_projects with action "add" hands the team every project in the organization; with "remove" it strips the team of all of them.

Create, rename, or delete a FOSSA team group.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true. action="delete" additionally requires FOSSA_ALLOW_DESTRUCTIVE=true.

A team group has only two editable fields, so one tool covers all three actions rather than three near-identical ones. "create" needs name and default_role_id; "update" needs team_group_id plus both of them, because FOSSA's update endpoint replaces both rather than patching either; "delete" needs only team_group_id.

Deleting a team group removes its team associations and its own membership list. The teams inside it are not deleted and keep their own members, projects, and release groups. FOSSA offers no undo. To change which teams are in a group, use fossa_update_team_group_assignments.

Change what is assigned to a FOSSA team group: the teams it contains, or its members.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true. action "remove" and action "replace" additionally require FOSSA_ALLOW_DESTRUCTIVE=true, because both take an existing assignment away.

• "teams" takes team_ids and supports add and remove. FOSSA removes teams one at a time, so a remove naming several teams issues one request per team and is not atomic: an error partway through leaves the earlier removals applied. The ids that succeeded are reported back.

• "users" takes users, a list of objects with the keys id and, for the add and replace actions, roleId, and supports all three actions.

Removing a team from a group does not delete the team. Action "replace" on users sets the group's membership to exactly what is named and removes everyone else.

Create, update, or delete a custom FOSSA role.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true. action="delete" additionally requires FOSSA_ALLOW_DESTRUCTIVE=true.

A role is a scope plus a permission list, so the three actions share one shape and one tool. "create" needs scope ("organization" or "team"), name, and description; "update" needs role_id and at least one of name, description, or permissions; "delete" needs only role_id.

Each entry in permissions is an object with the keys resourceType and action, both drawn from fossa_list_roles section "permissions" — FOSSA rejects a pair that is not in that catalog. Passing permissions on an update replaces the role's entire permission list, so send the full set, not a delta; omit it to leave the permissions alone. A role's scope cannot be changed after creation.

Only custom roles can be edited or deleted. FOSSA refuses to delete a built-in role, and refuses to delete any role still assigned to a user, so a delete cannot silently strip someone's access.

Create a FOSSA service account, optionally with API tokens.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

A service account is a non-human user that has to be able to do something, so FOSSA requires an organization role (org_role_id), a team assignment (team_id with team_role_id), or both. List the available role ids with fossa_list_roles.

Requesting a token returns its secret value in the response, once. FOSSA does not show it again, and a full-access token carries the same authority as the role it is attached to. Leave both token switches off unless the token is actually needed, and treat the result as a credential: it will appear in this conversation's transcript and in any log that records tool output.

List every package label defined in the organization.

Read-only. Package labels tag dependencies, not projects — use fossa_list_organization_labels for the labels that tag projects. The numeric id of each label here is what the assignment tools take as label_id. FOSSA answers 402 or 403 for organizations on the Free plan.

List which package labels are assigned to which packages.

Read-only. Every filter is optional; with none supplied FOSSA returns every assignment in the organization. include_package_wide_labels adds the labels assigned to all versions of the package when filtering by one version, and include_revision_scoped_labels adds revision-scoped labels under a project scope. The id of each assignment is what fossa_unassign_package_labels removes.

List the organization's project labels, or read one by id.

Read-only. These are the labels that tag projects — the ones fossa_apply_project_label applies and that fossa_list_projects and fossa_list_issues filter by. Package labels are a separate resource; see fossa_list_package_labels. With label_id the response includes the locators of the projects carrying that label.

Create one or more package labels in the organization.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

This creates label definitions only; nothing is tagged until fossa_assign_package_labels or fossa_bulk_assign_package_label binds one to a package. FOSSA answers with the labels it created, including the ids the assignment tools need.

Permanently delete one or more package label definitions.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

Deleting a definition removes it everywhere it is assigned, across every package, project, and revision in the organization — the blast radius is much larger than the id list suggests. To remove a label from one package without destroying the label, use fossa_unassign_package_labels instead.

Assign one or more existing package labels to a single package.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Additive: existing assignments are left alone and duplicates are ignored. Exactly one of package_version and apply_to_all_versions must be given — FOSSA reads a missing version as "every version of this package", so the wide form has to be asked for by name. scope_id identifies the project or revision and must be omitted for org scope.

Assign one package label to many packages in a single call.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

Additive, and every target is named: this endpoint has no "all packages matching a filter" mode, so the label reaches exactly the locators listed. Each locator must include its version, as in npm+lodash$4.17.21. With apply_to_all_versions=true the version part is ignored and the label is assigned to every version of each named package instead.

Replace a package's label assignments at one scope with an exact desired state.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

This is a reconcile, not an addition: FOSSA removes every existing assignment for this package and scope that new_label_ids does not mention. Read the current state with fossa_list_package_label_assignments first, or labels applied by someone else will disappear. new_label_ids maps a package version — or the literal all for assignments covering every version — to the list of label ids that should be assigned for it; an empty list clears that version. Use fossa_assign_package_labels when the intent is to add without removing.

Remove specific package label assignments.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

assignment_ids are the id values from fossa_list_package_label_assignments — the id of the assignment, not of the label. The label definitions themselves are untouched; only these bindings go away.

Create a new organization label for tagging projects.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true.

The label is created unattached; fossa_apply_project_label puts it on projects. FOSSA restricts this endpoint to premium plans and answers 403 otherwise. The response carries the new numeric id.

Permanently delete an organization label.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

The label is removed from every project carrying it. Check fossa_list_organization_labels with this id first: its response lists those projects, which is the only warning of how wide the change is. FOSSA restricts this endpoint to premium plans. Projects themselves are not affected beyond losing the tag.

Read one or more sections of a FOSSA organization's settings: the defaults new projects inherit, the package registries scans use, notification and privacy defaults, and the authentication configuration.

Read-only. Requires FOSSA_ORG_ID. Each section is a separate FOSSA request, so ask only for what is needed. Sections are named after their endpoint: "authentication", "general", "integrations-custom-license-scans", "integrations-slack", the "languages-" registry settings (bower, gem, git, mvn, npm, nuget, pip, pod), and the "projects-" defaults (github-status-checks, hidden-snippet-urls, issues-container, issues-licensing, issues-quality, issues-security, notifications, privacy, quick-import-scan-methods, update-hooks). Credentials in the registry settings come back obfuscated by FOSSA.

Read a FOSSA organization's plan limits and current usage for contributors and release groups.

Read-only. Requires FOSSA_ORG_ID. Each limit reports usage, max, and unlimited. Defaults to both. Useful before creating a release group, which fails once the organization is at its limit.

Write one section of a FOSSA organization's settings, or push a section's organization defaults down onto every existing project.

WRITES TO FOSSA. Requires FOSSA_ORG_ID, FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true. Both actions destroy state, for different reasons, and some sections require more still; the tier is decided per call:

• action="replace" requires FOSSA_ALLOW_DESTRUCTIVE=true. The PUT replaces the whole section rather than merging into it, so a body that omits a key erases it, and FOSSA offers no undo.

• action="propagate" requires FOSSA_ALLOW_DESTRUCTIVE=true. It overwrites the named setting on every project in the organization, so its target set is unbounded regardless of the HTTP verb.

• section="authentication" also requires FOSSA_ALLOW_ADMIN=true, as does section="general" when values carries defaultRoleId or disableNonCustomTeamUserRoles.

action="replace" (the default) sends the section's PUT. It REPLACES the section rather than merging, so pass the whole section, not just the key being changed; re-read it with fossa_org_settings first. values is the body, keyed by FOSSA's own field names, and unknown keys are rejected before any request is made. Two sections take a bare JSON array instead and use items: "languages-pod" (a list of source URLs) and "integrations-custom-license-scans" (objects with name, matchCriteria, and optionally id).

action="propagate" sends the section's PATCH and takes fields, the organization defaults to push out. Only the ten "projects-*" sections support it, and each accepts its own field list.

One writable section is not readable: "sbom-report-defaults" sets the author and supplier stamped into generated SBOMs. To replace the organization's SAML single sign-on configuration, use fossa_update_saml_settings — it is not a section here.

Delete a FOSSA organization's logo.

WRITES TO FOSSA. Requires FOSSA_ORG_ID, FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.

target="logo" clears the organization's uploaded logo and nothing else. To remove the organization's SAML single sign-on configuration — the other organization-level delete in this part of the API — use fossa_delete_saml_settings.

List the OIDC identity providers this FOSSA organization federates with.

Read-only. Each provider is an issuer URL scoped to the organization or to one team; it is what a trust relationship points at. Pagination is by cursor: pass the last value from a previous page as prev. Filtering by team scope requires filter_scope_id. Requires a premium FOSSA subscription; other organizations get a 403.

No credential is returned: FOSSA's OIDC federation stores no client secret.

Show one OIDC provider: its issuer URL, its scope, and when it was created.

Read-only. FOSSA answers 401 rather than 404 when the provider does not exist, belongs to another organization, or is not visible to this token, so an "unauthorized" here does not necessarily mean the token is wrong.

List the service accounts that may be named in a new trust relationship for an OIDC provider.

Read-only. Use this before fossa_create_oidc_trust_relationship to find the user_id to grant. team_id is required when the calling token only has team-level permission to manage trust relationships.

Returns account ids, usernames, and email addresses — identity, not credentials.

List the OIDC trust relationships configured for this organization.

Read-only. Each one is a standing grant: a workload presenting a token from the named provider whose claims match becomes the named FOSSA user. This is the tool to read when auditing what can authenticate without a password — look at requiredClaims, and treat a sub that matches broadly as a finding.

No credential is returned; a trust relationship holds only audiences and claim rules.

Show one OIDC trust relationship: the issuer, the service account it grants, the accepted audiences, and the claims a token must carry.

Read-only. FOSSA answers 401 rather than 404 for a relationship that does not exist or belongs to another organization.

Register an OIDC identity provider that this FOSSA organization will trust.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

This is federated-identity configuration for the whole organization. Adding a provider does not by itself let anyone in — a trust relationship does that — but it is the first half of a password-less login path, and whoever can call this can choose which issuer FOSSA will believe. Enabling the ADMIN tier on a deployment that does not authenticate its callers grants that ability to every caller.

issuer must be the issuer URL exactly as the provider mints it in the iss claim. Use scope="team" with scope_id set to a team id to scope the provider to one team; org scope takes no scope_id.

Delete an OIDC provider and every trust relationship that points at it.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true, and FOSSA_ALLOW_DESTRUCTIVE=true.

The cascade is the point to be careful about: FOSSA deletes the provider's trust relationships with it, so every workload authenticating through this issuer stops being able to log in. Nothing here restores them — they have to be recreated by hand. List them with fossa_list_oidc_trust_relationships (filtering on provider_id) before deleting, so there is a record of what the cascade will take.

Grant a workload permanent password-less login to FOSSA as a specific service account, on the strength of an OIDC token.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

Read that first line literally. After this call, anything that can obtain a token from provider_id whose claims match required_claims can exchange it for a FOSSA API token belonging to user_id, with that account's permissions, indefinitely and without a password. Enabling the ADMIN tier on a server that does not authenticate its callers means every caller can create such a grant.

required_claims is a list of objects: claim (the claim name), value (string, number, or boolean), and optional hasWildcards (when true, * matches any run of characters and ? matches one). It must pin sub — the subject identifying the workload, such as repo:acme/service:ref:refs/heads/main. A sub value consisting only of wildcards is refused here, because it would match every subject the issuer ever signs. audiences lists the aud values FOSSA will accept.

Find user_id with fossa_list_oidc_provider_service_accounts. Use scope="team" with scope_id for a team-scoped grant.

Change which tokens an existing OIDC trust relationship accepts.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

Only audiences and required_claims can be updated; the user and provider are fixed at creation. Each list replaces the stored one rather than merging into it, so send the complete set — omitting a claim removes it and widens what can authenticate. As on create, a sub value that is only wildcards is refused.

Revoke one OIDC trust relationship, so tokens matching it no longer buy a FOSSA login.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true, FOSSA_ALLOW_ADMIN=true, and FOSSA_ALLOW_DESTRUCTIVE=true.

This is the revocation path for a leaked or over-broad grant, and it is not reversible from here: the audiences and claim rules are gone once deleted. Read it with fossa_get_oidc_trust_relationship first if it may need to be recreated. FOSSA API tokens already minted through it are not invalidated by this call; they expire on their own schedule.

Check that an OIDC trust relationship actually works, by performing the token exchange a CI job would perform.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

The FOSSA API token this mints is deliberately not returned. What comes back is the identity FOSSA resolved (user, provider, issuer, subject) and the credential's metadata (whether it is push-only, when it expires) with the token itself replaced by a placeholder. A live API token in a tool result is a credential in a model's context, a transcript, and every log downstream of it; that is not a trade this server makes, and there is no argument that turns it back on. A CI job that needs the real token should call POST /oidc/token-exchange directly.

So use this to answer "is my trust relationship configured correctly?", not to obtain a token. Note that the token is still minted and still valid until it expires (15 minutes to 12 hours) even though nobody here can read it.

token is the JWT the identity provider issued; username is the FOSSA service account to log in as. FOSSA reports an invalid token, an unknown provider, and "no matching trust relationship" all as a 400.

Replace the organization's SAML single sign-on configuration.

WRITES TO FOSSA. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_ADMIN=true.

This is how everyone in the organization logs in. It is a replacement, not a merge: the three required fields are always sent, so a call with the wrong entry_point or a stale cert breaks SSO for every user until it is fixed, and a call that points entry_point at an identity provider someone else controls hands them the organization. The API documents no endpoint that reads the current settings back, so there is no way to check what was there before or to restore it — capture it from the FOSSA web app first.

entry_point is the IdP's SSO URL, cert its X.509 signing certificate in PEM form, audience the SP entity ID. The role-management fields decide whether FOSSA or the IdP is authoritative for org roles and teams; leaving them unset keeps FOSSA authoritative (FOSSA's own default). organization_id falls back to FOSSA_ORG_ID.