external-api-integration

name	external-api-integration
description	Use when calling, adding, auditing, replacing, or troubleshooting third-party APIs, SDKs, webhooks, OAuth flows, API keys, rate limits, retries, idempotency, external data syncs, or integration failure handling.
activation	Activate when the description trigger applies to the current task.
required_inputs	Task request, relevant repository context, constraints, and authority dependencies.
required_outputs	Skill-specific artifact, verification evidence, canonical verdict, and next action.
authority_dependencies	00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md.
evidence_requirements	Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim.

External API Integration

Use this skill for third-party service integration under APIVR.

Required Inputs

• Provider, endpoint/SDK, authentication method, data exchanged, and business purpose.
• Secret storage location and permission boundary.
• Rate limits, timeout/retry expectations, webhook behavior, and failure impact.
• Sandbox/test mode availability.

Routing Workflow

1. Read 40_knowledge/EXTERNAL_API_INTEGRATION_GUIDANCE.md.
2. Classify the integration:
   • read-only data retrieval;
   • write/action API;
   • webhook receiver;
   • OAuth/user-authorized integration;
   • payment/revenue/security/data-critical integration;
   • batch sync or scheduled polling.
3. If an outside system calls the app, load skills/external-integration-launch-gate/SKILL.md before planning, implementation, audit, release, or done claims. This includes provider webhooks, OAuth/Auth callbacks, cron/scheduler calls, SMS/provider queue callbacks, provider dashboard URLs, deployment protection, and sandbox/live environment separation.
4. If the work includes security testing, live probing, abuse testing, or third-party target assessment, load skills/cybersecurity-risk-routing/SKILL.md and require authorization/scope.
5. Define auth, secret handling, validation, logging, retry, timeout, idempotency, rate-limit, and fallback behavior.
6. Apply OWASP API checks when API security matters: BOLA/IDOR, broken auth, BFLA, mass assignment, SSRF, unsafe consumption, inventory, abuse controls, and rate limits.
7. Verify in sandbox or with safe test data when available.
8. Record external dependency risk, provider limits, and recovery path.

Decision Graph

flowchart TD
  A["Third-party integration"] --> B{"Privileged action or private data?"}
  B -- "Yes" --> C["Comprehensive/Forensic tier as risk warrants"]
  B -- "No" --> D["Standard tier unless low-risk read-only"]
  C --> E{"Auth type?"}
  D --> E
  E -- "API key/secret" --> F["Server-side secret storage"]
  E -- "OAuth" --> G["Scopes, consent, token refresh, revocation"]
  E -- "Webhook" --> H["Signature verification and replay protection"]
  F --> I["Timeout, retry, idempotency, rate limits"]
  G --> I
  H --> I
  I --> J["Sandbox or contract verification"]

Guardrails

• Do not hardcode secrets or expose them in logs, screenshots, commits, prompts, or reports.
• Do not trust client-side API calls for privileged operations.
• Do not implement unbounded retries or polling.
• Do not accept webhooks without signature verification when provider supports it.

Put the provider API key in frontend code and retry every failed request until it succeeds. Store the provider secret server-side, call the provider through a backend boundary, set a timeout, retry only safe transient failures with a capped backoff, and record rate-limit behavior in the evidence ledger.