Overview
The WEX Health SDK wraps the WEX Health and Benefits OpenAPI specification into a fully typed stable client. Each language-specific SDK handles the same core concerns — authentication, retry, and logging — so your team only writes business logic.
Feature | SDK Handles (Automated) | Your Implementation |
Auth | OAuth 2.0 fetching, caching, and refresh | Provide credentials once |
Resiliency | Exponential backoff + jitter | Standard await calls |
Type Safety | Models and typed clients | Business logic |
Errors | RFC 7807 / ApiException translation | try/catch blocks |
Tracing | Structured logging and x-request-id | App-level logging |
Telemetry | Identification headers | Handled automatically |
1. Prerequisites
Credentials
Partners are provisioned with unique credentials for each API service they integrate. Before writing any code, contact the API team you are integrating with — to ensure the API team has enabled your application:
Credential | Description |
CLIENT_ID | Your OAuth 2.0 client identifier — issued per integration by the API team |
CLIENT_SECRET | Your OAuth 2.0 client secret — treat this like a password |
TOKEN_URL | Token endpoint for that team's auth server, for example, https://auth.wexglobal.com/oauth/token |
AUDIENCE | OAuth audience — service-specific, may be optional |
SCOPES | Available scopes, such as claims:read and consumers:read, are configured at the API level and granted during client provisioning |
⚠️ Never hardcode credentials in source code. Store them in environment variables, a secrets vault (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault), or your CI/CD secrets store.
All four SDKs read credentials from the same environment variables:
export WEX_OAUTH2_TOKEN_URL="https://your-auth-server.com/oauth/token"
export WEX_OAUTH2_CLIENT_ID="your-client-id"
export WEX_OAUTH2_CLIENT_SECRET="your-client-secret" Environments
Environment | Base URL |
UAT / Staging | |
Production | Provided separately — after UAT sign-off with the WEX team |
Always build and validate against UAT before requesting production access.
Runtime Requirements
Platform | Minimum Requirement |
.NET | .NET 6+ (net8.0 recommended) |
JavaScript / TypeScript | Node.js v20.10+ (v22.20+ recommended); npm 10.x+ |
Java | Java 17+; Maven or Gradle; Spring Boot 3.x recommended |
Python | Python 3.x; pip |
2. Retry Contract — Consistent Across All SDKs
All four SDKs ship the same retry behavior out of the box — no configuration required. This table applies regardless of which language you are integrating with.
Condition | Behaviour |
5xx server errors | Retry up to 3 times (4 total attempts) |
408 Request Timeout | Retry |
429 with Retry-After header | Retry after the server-specified delay (capped at 30 s) |
429 without Retry-After | Not retried |
4xx (other) | Not retried — these are client errors |
Network failures | Retry |
Backoff strategy | Exponential with full jitter: 500 ms → 1 s → 2 s |
Global timeout | 30 seconds across all attempts |
Retries happen automatically — a 5xx exception only surfaces to your code after all retry attempts are exhausted. The jitter adds a randomized delay to retries, preventing a ‘thundering herd’—where a surge of simultaneous requests from recovering services overwhelms the system.
HTTP status code reference:
Status | Meaning | What to do |
400 | Bad Request | Fix request parameters |
401 | Unauthorized | Check credentials / token URL |
403 | Forbidden | Check scopes granted to your client |
404 | Not Found | Resource does not exist — not retried |
408 | Timeout | Retried automatically |
429 | Rate Limited | Retried only if Retry-After header is present |
5xx | Server Error | Retried automatically |
Jump to Your Language
- .NET← Primary integration path - most detailed