API hosts and surfaces
Usagey has three API surfaces. Their paths and authentication models are intentionally different and must not be combined.
Public integration API
Use this API from your backend or the @usagey/sdk package.
| Environment | Base URL | Authentication |
|---|---|---|
| Sandbox | https://sandbox.usagey.com/v1 | usg_test_ API key |
| Production | https://api.usagey.com/v1 | usg_live_ API key |
Public endpoints include /usage/check, /usage/track, /checkout, and /events. For example, production usage tracking is https://api.usagey.com/v1/usage/track.
Dashboard management API
Routes beginning with https://usagey.com/api/billing/ are the dashboard control plane. They use the signed-in Usagey operator session and workspace permissions. The organizationId and env query parameters select the operator's billing workspace.
These routes are used by the Usagey dashboard. They are not SDK endpoints and must not be prefixed with https://api.usagey.com/v1 or https://sandbox.usagey.com/v1.
Customer portal API
Routes beginning with https://usagey.com/api/customer-portal/ support Usagey's hosted customer portal. They use the signed-in customer's portal session and enforce that customer's identity.
They are not API-key-authenticated SDK endpoints. Applications should send customers to the hosted portal rather than calling these routes from a backend integration.
https://api.usagey.com/v1/api/billing/... and https://sandbox.usagey.com/v1/api/customer-portal/... are not valid Usagey endpoints.