API keys and authentication

Get an API key

SCANOSS issues API keys for the hosted SCANOSS API (https://api.scanoss.com) under a commercial licence. To get one, contact sales@scanoss.com or support@scanoss.com. One key works for every tool on this page. Treat it as a password:

Keep it in your CI system’s secret store, and pass it to the tools as the SCANOSS_API_KEY environment variable.
Do not type it on a command line in CI. CI systems often write commands to build logs.
Do not commit it to a repository, and do not put it in scanoss.json.

What needs a key

Operation	Needs a key?
`scanoss-cli scan`, `scan wfp`, `results`, `enrich`, `dependencies`, and the lookup commands (`vulnerabilities`, `licenses`, `cryptography`, and others) against `https://api.scanoss.com`	Yes
`scanoss-cli wfp` (fingerprints only) and `scanoss-cli sbom` (offline conversion)	No. They never contact the API.
Any `scanoss-cli` command against a custom API URL	Only if that server requires one
Crypto Finder with SCANOSS remote rulesets	Crypto Finder sends your key when it downloads rulesets and when it fetches published dependency findings
Crypto Finder with local rules only (`--no-remote-rules --rules-dir <dir>`)	No
Direct calls to the SCANOSS API	Yes

scanoss-cli

Ways to provide the key

# 1. Environment variable (recommended for CI)
export SCANOSS_API_KEY="<your-key>"
scanoss-cli scan . --output results.json

# 2. Stored in your user config file (recommended for workstations)
scanoss-cli config set api-key "<your-key>"
scanoss-cli scan . --output results.json

# 3. Flag, for a single run
scanoss-cli scan . --api-key "$SCANOSS_API_KEY" --output results.json

config set writes to ~/.scanoss/settings.json. Run scanoss-cli config path to print the exact location.

Precedence

Each setting resolves in the same order. The first source that has a non-empty value wins:

--flag  >  environment variable  >  ~/.scanoss/settings.json  >  built-in default

Setting	Flag	Environment variable	Default
`api-key`	`--api-key`	`SCANOSS_API_KEY`	none
`api-url`	`--api-url`	`SCANOSS_API_URL`	`https://api.scanoss.com`
`proxy`	`--proxy`	`SCANOSS_PROXY`	none (`HTTP_PROXY`/`HTTPS_PROXY` are honoured)
`ca-cert`	`--ca-cert`	`SCANOSS_CA_CERT`	none

Check what is in effect

$ scanoss-cli config list
api-key  ********                 (env: SCANOSS_API_KEY)
api-url  https://api.scanoss.com  (default)
ca-cert  (unset)
proxy    (unset)

Config file: /home/you/.scanoss/settings.json

The CLI never prints the key. scanoss-cli config get api-key only reports whether a key is set, and exits 0 if it is and 1 if it is not, so you can use it in a script:

scanoss-cli config get api-key >/dev/null || echo "No SCANOSS API key configured"

Add --verbose to any command to log which source each setting came from. The CLI never logs the key’s value.

What happens without a key

If no key is set and the API URL is the default https://api.scanoss.com, every command that calls the API stops before it sends anything. It prints a “No API key provided” notice to stderr and exits with code 1. If the API rejects the key (HTTP 401), the CLI prints Unauthorized: missing or invalid API key and exits with code 1.

Rotate or remove a stored key

scanoss-cli config set api-key "<new-key>"   # overwrite
scanoss-cli config unset api-key             # remove

Crypto Finder

Ways to provide the key

# 1. Environment variable (recommended for CI)
export SCANOSS_API_KEY="<your-key>"
crypto-finder scan .

# 2. Stored in the Crypto Finder config file
crypto-finder configure --api-key "<your-key>"
crypto-finder scan .

# 3. Flag, for a single run
crypto-finder scan --api-key "$SCANOSS_API_KEY" .

crypto-finder configure writes to ~/.scanoss/crypto-finder/config.json. This file is separate from the scanoss-cli file. If the file is readable by other users, Crypto Finder restricts it to the owner when it loads it.

Precedence

Command-line flags (--api-key, --api-url)
Environment variables (SCANOSS_API_KEY, SCANOSS_API_URL)
Config file (~/.scanoss/crypto-finder/config.json)
Project settings (scanoss.json in the scanned directory)
Defaults (https://api.scanoss.com)

Because both tools read SCANOSS_API_KEY and SCANOSS_API_URL, one pair of environment variables configures both in the same pipeline.

Use a custom API URL

Point the tools at an on-premise SCANOSS deployment, or any other SCANOSS endpoint, with the API URL setting:

# scanoss-cli
scanoss-cli config set api-url https://scanoss.internal.example.com
# or: export SCANOSS_API_URL=https://scanoss.internal.example.com
# or: scanoss-cli scan . --api-url https://scanoss.internal.example.com

# Crypto Finder
crypto-finder configure --api-url https://scanoss.internal.example.com
# or: crypto-finder scan --api-url https://scanoss.internal.example.com .

scanoss-cli only requires a key for the default endpoint. Against a custom URL it runs without a key, so a deployment that does not use keys needs no extra setup.

Proxies and custom certificate authorities

scanoss-cli

scanoss-cli honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY without any flag. To override them, or to trust a private CA, use the flags or store the settings:

scanoss-cli scan . --proxy http://proxy.example.com:8080
scanoss-cli scan . --ca-cert /etc/ssl/corp-ca.pem

# Or store them once
scanoss-cli config set proxy http://proxy.example.com:8080
scanoss-cli config set ca-cert /etc/ssl/corp-ca.pem

--ca-cert adds a PEM file to the system trust store. Verification stays on, and the public API still works.
A stored or flag proxy takes precedence over HTTP_PROXY/HTTPS_PROXY.
scanoss-cli does not support proxy auto-configuration (PAC) files. Read the proxy address from the PAC file and pass it with --proxy.
--ignore-cert-errors turns off all TLS verification. Use it only to test against a self-signed internal endpoint. It cannot be stored in the config file.

Crypto Finder

Crypto Finder has no proxy or CA flags. It uses the Go standard HTTP client, which means it:

honours the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables
trusts the operating system’s certificate store

On Linux, add your corporate CA to the system store, or set SSL_CERT_FILE to a bundle that contains it. SSL_CERT_FILE replaces the default bundle, so the file must also contain the public root certificates.

Calling the API directly

Send the key in the x-api-key request header. Header names are not case-sensitive.

curl -sS "https://api.scanoss.com/v3/components/status" \
  --get --data-urlencode "purl=pkg:github/scanoss/engine" \
  -H "x-api-key: $SCANOSS_API_KEY"

See v3 API overview for request and response conventions.

CI example

Store the key as a secret in your CI system and expose it to the job as SCANOSS_API_KEY. The commands then need no key flag:

# SCANOSS_API_KEY is injected by the CI system from its secret store
scanoss-cli scan . --output scanoss-results.json
crypto-finder scan --output crypto-results.json .

Get started

Recipes

CLI reference

API reference

Self-hosting & knowledge base

Get an API key

What needs a key

scanoss-cli

Ways to provide the key

Precedence

Check what is in effect

What happens without a key

Rotate or remove a stored key

Crypto Finder

Ways to provide the key

Precedence

Use a custom API URL

Proxies and custom certificate authorities

scanoss-cli

Crypto Finder

Calling the API directly

CI example

​Get an API key

​What needs a key

​scanoss-cli

​Ways to provide the key

​Precedence

​Check what is in effect

​What happens without a key

​Rotate or remove a stored key

​Crypto Finder

​Ways to provide the key

​Precedence

​Use a custom API URL

​Proxies and custom certificate authorities

​scanoss-cli

​Crypto Finder

​Calling the API directly

​CI example

Get an API key

What needs a key

scanoss-cli

Ways to provide the key

Precedence

Check what is in effect

What happens without a key

Rotate or remove a stored key

Crypto Finder

Ways to provide the key

Precedence

Use a custom API URL

Proxies and custom certificate authorities

scanoss-cli

Crypto Finder

Calling the API directly

CI example