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.

Why use a skill

Give findings a place in the register

A skill teaches the agent to prepare a finding, review possible duplicates and register the result where your team can assign, discuss and track it. Repeated assessments still need duplicate review; findings are not automatically merged merely because their wording is similar.

Step 1

Create a token

An administrator does this once, under Account → API Tokens. API access is available on Pay-per-use and Pro. 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 administrator-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.

Step 2

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.

Step 3

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_TOKEN

Is it OK to just point the agent at a local file?

It 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 workflow

Follow the API review and job lifecycle

The skill guides the agent through preflight, candidate review and finalisation. It then reads the outcome before continuing with changes, treatment or reassessment. Some operations return a durable job, which the agent must poll to completion.

Keep the downloaded guide current and preserve its instructions for idempotency, permissions and rate limits. The REST API walkthrough owns the worked request example and recovery steps.

The short version

Wiring-in checklist

On either paid plan, an administrator 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.

Wiring an agent into SecurityTrackr with skills.