> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys and authentication

> Get a SCANOSS API key and give it to scanoss-cli, Crypto Finder, or your own API client. Covers flags, environment variables, config files, precedence, custom API URLs, proxies, and custom CAs.

## 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](mailto:sales@scanoss.com) or
[support@scanoss.com](mailto: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

```bash theme={null}
# 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

```console theme={null}
$ 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:

```bash theme={null}
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

```bash theme={null}
scanoss-cli config set api-key "<new-key>"   # overwrite
scanoss-cli config unset api-key             # remove
```

## Crypto Finder

### Ways to provide the key

```bash theme={null}
# 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

1. Command-line flags (`--api-key`, `--api-url`)
2. Environment variables (`SCANOSS_API_KEY`, `SCANOSS_API_URL`)
3. Config file (`~/.scanoss/crypto-finder/config.json`)
4. Project settings (`scanoss.json` in the scanned directory)
5. 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:

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
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](/en/latest/developer-tools/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:

```bash theme={null}
# 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 .
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.