Configuration fundamentals

What you’ll configure

Most teams start with three essentials:

• Environment base URL: where the API is reachable
• Authentication: how requests are authorized
• Runtime controls: timeouts, retries, and safe defaults

If you’re still early in setup, start with Getting started and return here when you’re ready to stabilize your first runs.

Base URL and environments

Define one environment at a time (dev → stage → prod):

• Use a stable DNS name (avoid per-developer hosts)
• Keep “dev” and “stage” separate to reduce noisy failures
• Validate the spec’s servers entries match your base URL

Recommended approach

• Start with one environment (dev or stage) and get a clean run first.
• Add additional environments only after auth + test data are stable.

Authentication

Pick the simplest auth mechanism that matches how your API is secured in the target environment.

API key

• Store the API key as a secret (never commit it).
• Pass it as a header (for example, x-api-key) or query param if your API requires it.

Bearer token (OAuth/JWT)

• Use Authorization: Bearer <token>.
• Ensure the token has scopes for the endpoints being tested.
• Refresh tokens automatically in CI if tokens are short-lived.

Basic auth (if applicable)

• Use Authorization: Basic <base64(username:password)>.
• Prefer a dedicated test account with least privilege.

Timeouts and retries

To avoid false failures:

• Start with a reasonable request timeout (for example 10–30 seconds).
• Retry only for transient errors (timeouts, 502/503), not for deterministic 4xx errors.

Test data strategy (recommended)

Stable test runs require predictable data:

• Seed required entities before tests run
• Use unique IDs per run to avoid collisions
• Clean up only when needed (prefer isolated test data namespaces)

Security and secrets

Treat configuration as production-grade:

• Keep secrets in your secret manager (GitHub Secrets, Vault, etc.)
• Rotate keys/tokens regularly
• Restrict tokens to least privilege and least environment access

Common pitfalls (and fixes)

• 401/403 across many endpoints: token is missing, expired, or under-scoped. Verify scopes/roles and header format.
• 404 for valid endpoints: base URL doesn’t match the spec’s server/path configuration. Confirm servers and gateway routing.
• Flaky timeouts: start with higher timeouts, then tighten once the environment is stable.
• CI failures only: CI secrets aren’t wired correctly (different env vars/secret names).

What to read next

• Initial configuration
• Public API (for CI/CD integration)
• Test configuration (environment + data parameters)