The whole integration is three moves: create a token, download the skill, hand both to your agent. The skill is the operating manual that teaches an LLM how and when to call the API; the token is what lets it. After that the agent can register findings and work them through their lifecycle on its own. Here's the flow, the endpoints the agent will lean on, and how to hand over a long-lived credential without leaking it. This is the practical companion to the REST API overview, which covers the endpoint reference and auth model.
Better than a finding in a markdown file
Here's the problem this solves. Point an agent at a target today, or ask it to run a vulnerability assessment, and the findings land in a markdown file or scroll past in the chat. No risk rating, no owner, no status, no history, and nothing checking whether you already knew about half of them. Next week the file is stale and the findings are forgotten. The scan happened; the tracking didn't.
With the skill loaded, the agent registers each finding as an observation instead of writing it to a file. Now it's in your register: scored for likelihood and impact, categorised against ISO 27002 and NIST CSF, auto-linked to related findings, given a status, and visible to your team in the UI. Re-running the scan doesn't create noise, because duplicate detection folds repeats into the findings you already have. The skill is just the instruction layer that tells the agent how and where to file what it finds, so the same assessment that used to end in a markdown dump ends in a tracked, presented risk register instead.
Create a token
An owner does this once, under Account → API Tokens. API access is a Pro feature, so the tab is only there on a Pro plan. Give the token a name that says which integration it's for, so a stale one is easy to spot later.
Two choices matter here:
- Role. Pick the lowest one that does the job. A scanner that only files findings wants contributor; a read-only dashboard wants auditor. There's no owner-level token by design.
- Expiry. Choose 30 days, 90 days, 1 year, or never. It defaults to 90 days, which is good rotation hygiene. Prefer a dated expiry over never, especially for a token that lives on a laptop. You can revoke at any time regardless.
The plaintext token is shown exactly once, at creation. Copy it then; we only ever store a hash, so there's no way to see it again. If you lose it, revoke it and create a new one. An org can have up to ten active tokens at a time.
Download the right skill
A skill is a short document that teaches an agent how to use the API: setup, auth, the preflight-review-finalize workflow, the request shape, idempotency, and the error table. It ships in two variants, both one-click downloads on the same API Tokens tab, and both describe the exact same API because they're generated from one source.
- Claude (SKILL.md). A drop-in Agent Skill for Claude and Claude Code. Put it in your skills folder and the agent auto-discovers it, loading the instructions only when a finding needs tracking. Served at /api/v1/skill/claude.
- Generic (Markdown). A provider-neutral guide for OpenAI, Mistral, LangChain, and anything else. It points at the OpenAPI spec, which those frameworks ingest to generate tool definitions. Served at /api/v1/skill/generic.
Both skills reference the machine-readable contract at /api/v1/openapi.json. For a Claude agent the SKILL.md is usually enough on its own; for a generic framework you'll typically load the OpenAPI JSON to build the tools and use the guide as the prose that tells the model when to reach for them.
Give the agent the token, safely
This is a long-lived credential going into an autonomous system, so treat it like any other secret. The one risk that matters most is the token ending up in the model's context window: once it's in the transcript it can be logged or retained, and you should treat it as leaked. So the rule is that the tool reads the token, the model never sees it.
- Inject it, don't embed it. Put the token in an environment variable or a secret manager. The skills read it from SECURITYTRACKR_API_TOKEN. Never paste it into a prompt, a code comment, or a committed file.
- Keep it out of the context window. The model needs to send the token in a header, not read it. Wire it in at the HTTP layer so it never lands in the transcript the model sees.
- One token per integration. Separate tokens mean you can revoke one without breaking the others, and last-used times actually tell you which integration is which.
On a laptop, driving this through a coding agent like Claude Code, the safe pattern is to load the token into the environment yourself before you start the agent, from a real secret store, so it never transits the model at all:
# Best: pull from a secret manager into the env var at session start.
export SECURITYTRACKR_API_TOKEN="$(op read 'op://Private/securitytrackr/token')" # 1Password CLI
# or macOS Keychain:
export SECURITYTRACKR_API_TOKEN="$(security find-generic-password -s securitytrackr -w)"
# Acceptable: a gitignored file OUTSIDE any repo, locked down, sourced (not printed).
chmod 600 ~/.config/securitytrackr/env # contains: export SECURITYTRACKR_API_TOKEN=sgt_live_...
source ~/.config/securitytrackr/env
# Then let the agent's tool attach it per request; the model never reads the value:
# Authorization: Bearer $SECURITYTRACKR_API_TOKENIt can be, but only if the file lives outside version control, is locked down (chmod 600), and gets loaded as an environment variable rather than read into the conversation. The failure mode is the agent running cat on the file and echoing the token into the chat, where it's now in the transcript. Safer to export the env var yourself before launching the agent, so the token never reaches the model. Either way, keep the blast radius small: use a low-privilege token (contributor or auditor), a short expiry, one per machine, and revoke it the moment you're done or suspect exposure.
The API Tokens tab has a short Handling tokens securely panel covering the same ground. If a token might be exposed, revoke it there; it stops working immediately.
The lifecycle it drives
Once wired in, the agent has a full loop, not just a create call. It can register a finding, read it back, record what it did, and ask for a fresh risk score. The steps are kept deliberately separate so “record what I did” and “tell me the new risk” are two distinct calls.
- Register. POST /observations/preflight with a stable Idempotency-Key, review every returned candidate, then POST /observations/ingest-attempts/{attemptId}/finalize for the exact review revision. The server enriches the proposal: it drafts the title and summary, scores likelihood and impact, proposes ISO and NIST areas, drafts recommendations, and links related findings. Direct POST /observations is refused with 428.
- Read. GET /observations/{id} to read the full finding back, including the ids the agent needs to reference recommendations later. (The list endpoint returns lightweight summaries; the detail lives here.)
- Record. PATCH /observations/{id} to update mitigating controls, recommendation statuses, and the treatment decision (mitigate or accept). No AI here, it's a plain field update.
- Re-score. POST /observations/{id}/reassess with an idempotency_key. It returns 202 with an actor-scoped durable AI job; poll that job, then read the observation for the new likelihood, impact, and derived rating.
- Close out. Move a completed recommendation into existing controls with the deploy endpoint, which also returns a durable AI job, then mark the whole finding mitigated once its treatment is done.
Finalize may involve several AI steps and can take tens of seconds, depending on the provider and model. Set a generous client timeout and retry safely with the same idempotency key if the request is interrupted. Pass enrich: false to skip server-side enrichment and store your exact values fast.
Idempotency and rate limits
Agents retry, and a slow enriched finalize is exactly the kind of call that gets retried mid-flight. Send an Idempotency-Key header on preflight and a retry with the same key returns the original ingest attempt instead of starting another review.
# 1. Prepare the candidate review.
curl -s -X POST https://app.securitytrackr.com/api/v1/observations/preflight \
-H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: scan-2026-08-24-lb-prod-01-tls10" \
-d '{ "user_observation": "TLS 1.0 enabled on lb-prod-01." }'
# -> { "attempt_id": "...", "review_revision": 1, "candidates": [...] }
# 2. Review every candidate, then finalize that revision.
curl -s -X POST https://app.securitytrackr.com/api/v1/observations/ingest-attempts/$ATTEMPT_ID/finalize \
-H "Authorization: Bearer $SECURITYTRACKR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "review_revision": 1, "candidate_dispositions": [] }'Every response carries RateLimit-* headers so an agent can pace itself. Honour those values and Retry-After when present rather than assuming a fixed capacity.
Wiring-in checklist
- On Pro, an owner creates a contributor or member token under Account → API Tokens and copies it once. Use an auditor token only for read-only integrations.
- Download the Claude SKILL.md or the generic guide from the same tab.
- Drop the skill into your agent, and load the OpenAPI spec too if it's a generic framework.
- Load the token into SECURITYTRACKR_API_TOKEN from a secret store, never in the prompt or a committed file.
- Let the agent preflight findings, review candidates, finalize them, then read, record, and reassess them through the lifecycle.
- Send an Idempotency-Key on preflight and honour the RateLimit headers.
- Revoke the token the moment you suspect it's exposed.
Want the design detail behind the token format, the auth model, and the full endpoint reference? That's the companion piece: Integrating via the REST API.