Docs / Quickstart

Quickstart

From nothing to a working account, an ingest token and your first usage reading in about five minutes. Every step is shown as a dashboard action and as a command.

1. Create an account

Sign-up is open and starts you on the free plan: cloud-hosted, no card. Use the sign-up page, or the API. The password needs 8 to 256 characters; name is optional.

curl -X POST https://protet.io/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "a-strong-password", "name": "Your Company"}'

The response is always the same shape, whether or not the address is already registered:

{ "status": "pending_verification", "customer_id": "..." }

2. Verify your email

We email a link of the form https://protet.io/verify?token=.... Open it in a browser, or post the token yourself:

curl -X POST https://protet.io/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<token from the email link>"}'

{ "status": "active", "license": null, "pull_token": "..." }

license is null on the cloud free plan: cloud accounts have no license file. The pull_token is for on-prem bundle pulls and is not needed for the cloud plan. No email? Check spam, then ask for a new link:

curl -X POST https://protet.io/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

3. Mint an ingest token

The ingest token is the one secret the GitHub Action or your own collector uses. In the dashboard, open Connect your cluster and press Mint refresh token. It is shown once; store it as a secret straight away (for GitHub, a repository secret named PROTET_TOKEN).

With the API, log in and call the mint endpoint with the session token:

TOKEN=$(curl -s -X POST https://protet.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "a-strong-password"}' \
  | python3 -c 'import sys, json; print(json.load(sys.stdin)["access_token"])')

curl -s -X POST https://protet.io/portal/ingest-token \
  -H "Authorization: Bearer $TOKEN"

{ "token": "..." }

This is a long-lived refresh token (valid 90 days by default). The collector or Action trades it for short-lived access tokens, so there is nothing to rotate mid-build. See Integrations for the exchange.

4. Check your usage

The free plan meters build sessions per calendar month: 500 sessions a month. Every analysed build returns a result, benign or malicious. The dashboard shows your usage, or query them with the refresh token from step 3 (or the logged-in session token):

export PROTET_TOKEN="<your refresh token>"
curl -H "Authorization: Bearer $PROTET_TOKEN" https://protet.io/v1/usage

{
  "period": "2026-09",
  "resets_at": "2026-10-01T00:00:00Z",
  "sessions": { "used": 125, "limit": 500 }
}

A build session is one monitored pod's lifetime, from the first observed execve to pod teardown. A build in flight is never cut off if the cap is reached during it; only a new session past the cap is held back.

5. Watch a build (preview)

The design: add protet/monitor@v1 to a workflow, and Protet watches the commands the job runs and reports a verdict on the run and the pull request. Your build steps do not change.

- uses: protet/monitor@v1
  with:
    token: ${{ secrets.PROTET_TOKEN }}

Today this flow does not reliably produce a verdict, so treat it as a way to try the integration, not as protection. The full workflow, inputs, permissions and the exact limitation are on Install: GitHub Action.

6. Read the Intel feed

The Protet Intel feed needs no account. These two commands print how many npm package versions Protet has screened and confirmed:

curl -s https://protet.io/intel/v1/stats.json | python3 -m json.tool | head -20
curl -s https://protet.io/intel/v1/all/findings.ndjson | wc -l

See the Intel feed guide for the OSV, Atom and NDJSON endpoints.

Next

• On-prem instead of cloud? On-prem install.
• Every option and variable: Configuration reference.
• Something failed? Troubleshooting.