APIsec NG Examples (Python)

Minimal, production-quality Python examples for interacting with the APIsec NG API directly. These scripts run with uv, use curl under the hood (no external Python deps), and emit machine-friendly JSON envelopes ideal for CI/CD pipelines.

Authentication — read this first

The scripts use one credential to authenticate to APIsec NG: a Personal Access Token (PAT) set as APISEC_API_TOKEN in your .env file. There is no username/password login flow against the APIsec API.

# Required in config/.env
APISEC_API_TOKEN='your-pat-here'   # "Bearer " prefix is added for you

config/auth-examples/ is a different thing. Those template files (with username / password / client_id fields) are not for authenticating to APIsec. They're for the optional case where you need to fetch a protected OpenAPI spec from your own backend (e.g., a Boomi gateway, an Azure-AD-protected service) before sending it to APIsec. If your spec is a local file or a public URL, ignore that folder entirely. See config/auth-examples/README.md for details.

What you can do

• Register an application from an OpenAPI spec (file or URL)
• Register an application with a host and spec together
• Add or list instances, show app and instance details
• Refresh an application's spec
• Trigger a scan and optionally wait for completion
• Delete an application
• (Optional) Fetch protected OpenAPI specs (API Key / Basic / Bearer / OAuth2 client-credentials / custom headers)

All scripts follow an atomic approach — each does one thing well and chains cleanly into CI/CD workflows.

Features

• Consistent JSON envelope for every command (script, version, timestamp, request_id, status, data | error)
• Actionable error messages with non-zero exit codes for pipelines
• Timestamped receipts written to output/ for auditability
• Safe-by-default filesystem writes; --force to override guardrails
• Token normalization adds Bearer automatically when needed
• --verbose surfaces HTTP diagnostics

Prerequisites

• bash or zsh shell
• curl and jq installed
• uv (manages Python automatically)

Quick Start

1. Configure environment

cp config/.exampleenv config/.env

Edit config/.env and set your APIsec NG Personal Access Token:

APISEC_API_TOKEN='your-pat-here'     # "Bearer " prefix not required
APISEC_TENANT="https://<your-tenant>.apisecapps.com/"

Then load it:

set -a; source config/.env; set +a

On some Linux shells: set -a; . config/.env; set +a

2. Run a workflow

# Register an app from a local OpenAPI spec (creates one app + instance per spec server URL)
uv run python ./scripts/register_app_from_spec.py \
  --app-name "MY-FIRST-APP" --spec-file openapi.json | jq .

# Capture IDs from the response
export APISEC_APP_ID="<applicationId-from-response>"

# List instances
uv run python scripts/list_instances.py --app-id "${APISEC_APP_ID}" --format table

# Trigger a scan and wait for it to finish
export APISEC_INSTANCE_ID="<instanceId-from-response>"
uv run python scripts/run_scan.py \
  --app-id "${APISEC_APP_ID}" \
  --instance-id "${APISEC_INSTANCE_ID}" --wait

3. Interactive setup

uv run python ./scripts/setup_app.py --interactive \
  --app-name "MY-INTERACTIVE-APP" --spec-file openapi.json

Project layout

scripts/             Atomic entry-point scripts (one operation per script)
scripts/examples/    Example workflow chains
lib/                 Shared helpers (no external Python dependencies)
config/              .exampleenv and (optional) spec-fetch auth profile examples
tests/               Unit, integration, and e2e tests
openapi.json         Public demo OpenAPI spec (crAPI / cozy-solace) for smoke tests

Two independent auth contexts (deeper dive)

Context	What you set	Where it's used
Talking to APIsec NG	APISEC_API_TOKEN (PAT) in .env	Every script — sent as Authorization: Bearer <token>
Fetching your own protected OAS (optional)	A JSON file from config/auth-examples/ filled in and passed via --auth-from	Only fetch_specs_with_auth.py and register_app_from_spec.py --auth-from

These never mix. The PAT is the only credential the APIsec API itself ever sees.

Enterprise-ready qualities

• Deterministic CLI surfaces suitable for CI/CD
• Structured, actionable errors with explicit exit codes
• Audit-friendly timestamped receipts
• Guardrails against accidental writes outside the examples directory

Contributing

• Optional pre-commit hooks: uv run pre-commit install && uv run pre-commit run --all-files
• Lint / type: uv run ruff check . && uv run mypy .
• Tests: uv run pytest ./tests -q

License

MIT — see LICENSE.md.