Connect
Private Hugging Face repositories, the API, CI gates and webhooks; what each option needs and how to check it works.
The Connect page in the app shows what your organization has set up. Each option below lists what it needs and a command to check it.
| Option | Status | Needs |
|---|---|---|
| Hugging Face | available | nothing for public models; a read-only token for private or gated ones |
| API | available | an API key |
| CI gate | available | an API key stored as a CI secret |
| Webhooks | available | a public https:// endpoint |
| Cloud bucket (S3, GCS) | coming later | — |
| Auto-scan on new versions | coming later | — |
| Runner on your own GPUs | coming later | — |
Requests for an option that is not available yet are refused with a clear message (422); nothing runs halfway. For
example, {"model": "s3://acme-models/kyc"} answers "cloud buckets (s3://, gs://) are not available yet", and
{"run_on": "runner"} answers "only 'cloud' is available today".
The commands below use two shell variables:
export API=https://api.neuronlens.com/v1/integrity
export K="Authorization: Bearer $NEURONLENS_API_KEY"
Hugging Face
Public models need nothing: scan hf://org/name.
Private or gated models need a Hugging Face token that can read them. An organization admin adds it once:
- On Hugging Face, open Settings → Access Tokens and create a token of type Read (or a fine-grained token with read access to the repositories you want scanned). Tokens that can write are refused.
- In the app, open Connect → Hugging Face, paste the token and save. Or through the API:
curl -s $API/sources -H "$K" -H "Content-Type: application/json" \
-d '{"kind": "huggingface", "token": "hf_..."}'
# -> {"kind": "huggingface", "status": "connected", "hint": "hf_…ZKuZ (your-hf-user)"}
The token is checked with Hugging Face, stored encrypted, and used only while scanning your organization's models.
Remove it at any time on the page or with POST $API/sources/huggingface/remove.
| You see | Meaning |
|---|---|
scan fails with needs_token | the repository is private or gated and no token can read it: add or update the token |
422 "did not accept this token" | the token is invalid or expired |
422 "use a read-only token" | the token can write; create a Read token |
403 "needs the admin role" | only owners and admins can change the token |
API
Create a key under Profile → API keys, choosing the organization it acts for. The key acts as you, in that organization: its scans appear in the app under your name.
curl -s $API/whoami -H "$K" # organization, role, scans in the last 24 h
ID=$(curl -s $API/scans -H "$K" -H "Content-Type: application/json" \
-d '{"model": "hf://meta-llama/Llama-3.2-3B-Instruct"}' | jq -r .scan_id)
curl -s $API/scans/$ID -H "$K" | jq '{status, verdict, against_approved, report_url}'
Poll until status is done or failed. Every endpoint is in the API reference.
CI gate
Fail a build when the model you are about to ship is tampered or is no longer the approved version. Approve a version
first; the core of the step, after polling the scan into $R as in the API example:
[ "$(echo "$R" | jq -r .verdict)" != tampered ] || exit 1
[ "$(echo "$R" | jq -r .against_approved)" = matches_approved ] || exit 1
The complete GitHub Actions step, and notes for other CI systems, are in Gate a build.
Webhooks
Instead of polling, pass a webhook with the scan; we POST the finished scan to it, signed with our key:
curl -s $API/scans -H "$K" -H "Content-Type: application/json" \
-d '{"model": "hf://acme/kyc-assistant-v3", "webhook": "https://ci.example.com/hooks/neuronlens"}'
Webhooks must be public https:// addresses. See Webhooks for the body
and how to check the signature.
Check your setup
Run these once after connecting. Each line prints what you should expect.
curl -s $API/whoami -H "$K" | jq '{org, role}' # your organization and role
curl -s $API/sources -H "$K" | jq '.sources[] | {kind, status}' # huggingface: connected or not_set_up
curl -s $API/scans -H "$K" -H "Content-Type: application/json" \
-d '{"model": "hf://your-org/your-private-model"}' | jq .scan_id # then poll: status done, not needs_token