How to Test an OpenAPI Spec

Obtain your OpenAPI specification

You need an OpenAPI 3.x (JSON or YAML) or Swagger 2.x file. Common locations:

• Generated by your framework (FastAPI, Spring Boot, Express with swagger-jsdoc, etc.)
• Available at /openapi.json, /swagger.json, or /docs on your API server
• Checked into your repository as openapi.yaml or api-spec.json

If your API doesn't have a spec, see REST API Testing for specless scanning.

Validate your spec

Ensure the spec is valid before scanning:

# Using the openapi-spec-validator Python package
pip install openapi-spec-validator
openapi-spec-validator ./openapi.yaml

Fix any validation errors — invalid specs can cause NAT to miss endpoints.

Run the scan with your spec

nat scan \
  --url https://api.example.com \
  --spec ./openapi.yaml

Or use a live spec URL:

nat scan \
  --url https://api.example.com \
  --spec https://api.example.com/openapi.json

Add authentication

Most APIs require credentials. NAT will test unauthenticated access automatically, but providing credentials enables deeper testing:

nat scan \
  --url https://api.example.com \
  --spec ./openapi.yaml \
  --auth-type bearer \
  --token "$YOUR_TOKEN"

Add a second user token for BOLA testing

Providing two different user tokens enables NAT to test cross-user resource access (Broken Object Level Authorization):

nat scan \
  --url https://api.example.com \
  --spec ./openapi.yaml \
  --auth-type bearer \
  --token "$USER_A_TOKEN" \
  --secondary-token "$USER_B_TOKEN"

Review the report

nat report --open

Look for:

• Critical/High findings — address these immediately
• BOLA findings — require cross-user data access to be fixed
• Spec coverage — "X of Y endpoints tested" shows how many spec endpoints were reachable