API & Custom Integrations

To use the FOSSA CLI or API, you must provision API tokens. To create API tokens, go to Organization Settings > Integrations > API or API User After a token is created, it cannot be changed.

📘

API Tokens are displayed one time, upon creation. Please copy and store your token securely. It will never be displayed again

API Tokens

API tokens in FOSSA are secure credentials used to access the FOSSA API.

Push-Only Token

Creating a push-only API token restricts the users access to only allow uploading builds. The API token will be restricted from reading anything about the project or editing existing information.

This token was created with open source project maintainers in mind. The FOSSA API key is required to be set as an environment variable or included in the configuration file whenever integrating FOSSA with a CI system, such as TravisCI. This has the unfortunate side effect of exposing the API key to anyone who makes a pull request. Restricting a user's access with a push-only API token is the best way to combat any malicious actors. When creating this type of token, ensure the Push Only checkbox is checked.

Full API Token

Grants complete API permissions, including reading, creating, updating, and deleting resources, managing projects, accessing organizational or project data and many more.

API tokens should be kept secure and used only in trusted environments, as they effectively impersonate your identity and can perform any action you could in the FOSSA web interface. Make sure your account has the appropriate permissions based on how you intend to use the token.

API User Tokens

An API User is a special FOSSA account created to generate API tokens that operate independently of your organization’s SSO configuration. This allows automated systems or CI/CD pipelines to interact with the FOSSA API without relying on a standard user login.

A role can be assigned to the API User. Ensure the selected role aligns with the intended use: for example, default roles like Editor or Admin can actually utilize either Full Access or Push-Only tokens.

From an API User, you can generate:

Push-Only Token

Can only send data to FOSSA, safe for CI/CD environments.

Full API Token

Grants complete API permissions, including reading, creating, updating, and deleting resources, managing projects, accessing organizational or project data and many more.

Token Usage Examples

Whether you’re using a standard API token or an API User token, here are simple examples for both Push-Only and Full Access tokens.

Push-Only Token

FOSSA_API_KEY=<push_only_token> fossa analyze

The analyze subcommand pushes the dependency graph to FOSSA’s backend services. Push-Only tokens are safe to use in CI/CD environments since they cannot read or modify other data. This is the most common way to use a Push-Only token.

Full API Token

To interact with the FOSSA API using a Full Access token, you can use curl as a template:

curl -H "Authorization: Bearer <full api token>" "https://app.fossa.com/<API endpoint>"

Full Access tokens provide programmatic control over your organization’s metadata, including the ability to read, create, update, and delete resources such as project data, dependency information, release group management, and more.

FOSSA API Documentation

The FOSSA API is available to enterprise customers for building custom integrations.

With the FOSSA API, you can fetch data about your projects and FOSSA’s analysis of them, enabling automation of workflows such as:

• Continuous Integration (CI) tasks
• Dependency management scripts
• Generation of custom documents or reports
• Any other custom functionality operating on your code or dependencies

For more information, contact [email protected].