Skip to main content
The SOAX API authenticates every request with an API key sent as a bearer token:
API key secrets start with s_live_. A missing, malformed, unknown, or revoked key returns:
API key ≠ package key. The API key (s_live_…) authenticates calls to api.platform.soax.com. The package key (a 10-character password, one per package) authenticates proxy traffic through proxy.soax.com:1337 — that’s the password field in connection strings and the value rotated by rotate package password. They are managed separately and are not interchangeable.

​
Getting a key

Create keys in the dashboard under Settings → API keys: click Generate new API key, choose a name and scopes, and optionally restrict the key to specific packages. The secret is displayed once, at creation — store it securely; it cannot be retrieved later. (Only a hash is stored server-side.) You can also create keys programmatically with POST /v1/api-keys/ — see Key lifecycle below.

​
Scopes

Each key carries a set of scopes, and each endpoint requires one. Calling an endpoint without the required scope returns:
GET /v1/api-keys/me is the one exception: any active key can call it, regardless of scopes. Use it to check what a key can do. Grant each key only the scopes it needs. A monitoring job that reads analytics needs proxy:analytics:read and nothing else.

​
Package restrictions

A key can be restricted to specific packages (package_ids). A restricted key:
  • only sees those packages in GET /v1/proxy/packages,
  • gets 404 (not 403) when requesting any other package — so the existence of packages outside the restriction is never revealed,
  • has its analytics results limited to those packages, even when it passes a broader package_ids filter.
A key with package_ids: null is unrestricted and can access every package in the organization.

​
Key lifecycle

Keys can manage keys, which lets you automate rotation without touching the dashboard:
  • Inspect — GET /v1/api-keys/me shows the calling key’s scopes, restriction, and rate-limit quota.
  • Create — POST /v1/api-keys/ (requires api-keys:write). To prevent privilege escalation, the new key’s scopes must be a subset of the caller’s, and its package restriction a subset of the caller’s restriction.
  • Revoke — DELETE /v1/api-keys/{key_id} (requires api-keys:write). Revocation is immediate and permanent: the key remains visible in listings with status revoked, but every request using it fails with 401. A key can revoke itself.
To rotate a key with zero downtime: create the replacement, deploy it, then revoke the old key.

​
Best practices

  • Store secrets in a secrets manager or environment variables, never in code or client-side bundles.
  • Use separate keys per service or environment, so one leak doesn’t require rotating everything and usage stays attributable (each key tracks last_used_at).
  • Scope keys down: read-only keys for dashboards and monitoring, api-keys:write only where rotation is automated.
  • Enable two-factor authentication on dashboard accounts that can manage API keys.