gasguide PSV API

1. Get a test API key from your gasguide account. Test keys start with gg_test_ and only work against sandbox endpoints.
2. Smoke-test your auth wiring:

   curl https://gasguide.app/api/v1/whoami \
     -H "Authorization: Bearer gg_test_<your-key>"
   
   # {
   #   "org_id": "...",
   #   "environment": "test",
   #   "scopes": ["psv:providers:read", ...],
   #   "rate_limit": { "per_minute": 1000, "remaining": 999 }
   # }

3. List the four canonical sandbox providers:

   curl https://gasguide.app/api/v1/sandbox/providers \
     -H "Authorization: Bearer gg_test_<your-key>"

4. When you're ready, swap your gg_test_ key for a gg_live_ key and point at /api/v1/psv/* instead of /api/v1/sandbox/*.

Every endpoint requires a bearer token in the Authorization header. Tokens are scoped to a single org + environment + capability set; mint them from your dashboard. The full token is shown ONCE at create — if you lose it, revoke and mint a new one.

Token format: gg_<env>_<prefix>_<secret> where <env> is live or test.

Per-key scopes gate which endpoints + which fields a token can see. The 403 response includes the missing scope so you can request the right one from your gasguide admin.

• psv:providers:read — list + detail providers
• psv:sanctions:read — flag details (severity, kind, summary)
• psv:results:read — historical PSV result rows
• psv:results:full — raw upstream payloads (admin tier)
• psv:enroll:write — enroll, disenroll, bulk CSV import
• psv:manual_run:write — trigger a one-off PSV run
• webhooks:read — list outbound webhook endpoints + deliveries
• webhooks:write — create + delete outbound webhook endpoints

Every endpoint returns either a success body or an error envelope. Both include request_id for correlation and X-Request-Id in the response headers.

// success
{
  "items": [ ... ],
  "next_cursor": "opaque_string_or_null",
  "page_size": 50,
  "request_id": "abc123"
}

// error
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry in 60 seconds."
  },
  "request_id": "abc123"
}

List endpoints use opaque cursor pagination. Pass ?cursor=<next_cursor> from the prior response.?limit= accepts 1..100, default 50.

Pass Idempotency-Key: <opaque> (≤200 chars) on every write request. Replays return the stored response for 24 hours. Reusing the same key with a different body returns 422idempotency_key_mismatch— that's a bug on your end, not a dedupe hit.

Default: 1,000 requests per minute per API key. Custom ceilings available on Enterprise. Every response includes X-RateLimit-Remaining; 429s include Retry-After.

Subscribe to real-time events. Outbound deliveries use Stripe- compatible HMAC-SHA256 signatures so your existing webhook verification code Just Works.

curl https://gasguide.app/api/v1/webhooks \
  -H "Authorization: Bearer gg_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/gasguide",
    "events": ["psv.flag.created", "psv.result.changed"]
  }'

# Response (201):
# {
#   "id": "...",
#   "url": "...",
#   "events": ["..."],
#   "secret": "<48-byte-base64url>",
#   "secret_note": "Store this secret -- it is NOT retrievable after this response."
# }

Delivery retry schedule: 0, 1m, 5m, 30m, 2h, 12h, 24h × 4 → dead-letter (matches Stripe). Verify the signature header (named X-GasGuide-Signature) with HMAC-SHA256 of {t}.{body} using your endpoint secret.

Test-key endpoints under /api/v1/sandbox/* return four canonical fixture providers regardless of your actual roster.

• Alex Rivera — clean, no flags. Happy-path testing.
• Brooke Tan — one minor flag (expired license). Renewal-UX testing.
• Carter Lee — multi-flag (critical DEA + moderate license + minor CSR). Severity-filter testing.
• Devon Park — OIG-LEIE mandatory exclusion. Highest-severity escalation testing.

Sandbox endpoints reject gg_live_ keys with 403live_key_rejected_on_sandbox. Sandbox response shape matches the production endpoints exactly, so integration tests carry to prod with zero changes.

Machine-readable OpenAPI 3.1 spec at /api/v1/openapi.json. Pin against it for SDK generation or live contract tests.

api@gasguide.app — integration support. Include your request_id for fastest triage.

Security findings: security@gasguide.app. See /.well-known/security.txt for scope and safe-harbor terms.