Ingest tokens
Ingest tokens authenticate agent scans. They are the only way for the agent to send data to the API.
How tokens work
- A user generates a token from the dashboard (+ Add machine or Rescan)
- The token is displayed once — copy it immediately
- The agent uses the token as a Bearer header:
Authorization: Bearer <token> - The token is consumed on first successful ingest
- The token cannot be reused
Security properties
| Property | Value |
|---|---|
| Length | 128 characters |
| Randomness | secrets.token_urlsafe(48) |
| Lifetime | Until used (no expiration) |
| Usage | Single-use (consumed on successful ingest) |
| Scope | Organization-level (any machine in the org) |
Why single-use?
Single-use tokens have a smaller attack surface than persistent credentials:
- A stolen token is worthless after the scan completes
- No long-lived secret sits on the machine between scans
- No rotation, revocation, or grace periods to manage
- Each scan is independently authenticated
Retry behavior
If a scan is a duplicate (same machine + same scan sequence), the API releases the token so the agent can retry without minting a new one. This handles network errors gracefully.
Generating tokens
From the dashboard
- Click + Add machine (new machine) or Rescan (existing machine)
- Copy the one-liner command that includes the token
From the CLI
ghostpsy-cli token create ingest <org-slug>
The token is printed to stdout. Use it immediately.