Authentication

The Proxio API uses one authentication scheme: a Bearer API key sent in the Authorization header. There is no second token, no cookie, and no separate auth domain.

Authorization: Bearer pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x

Every endpoint requires a valid key except the two public discovery routes: a GET on the base URL itself and GET /openapi.json.

Key format

A key looks like pxo_ followed by 40 base62 characters. It is generated from 30 cryptographically random bytes, so it carries roughly 240 bits of entropy.

• The full key is shown once, at creation. It is stored only as a SHA-256 hash, so Proxio can never show it to you again.
• Only a short prefix (the first 12 characters, e.g. pxo_9fJ2kQ7x) is retained for display, so you can tell keys apart in the dashboard.
• Lost keys cannot be recovered. Revoke and recreate instead.

Managing keys

Keys are created and managed in the dashboard under Settings → API keys, or programmatically through the API Keys endpoints themselves, so a pipeline can mint and revoke its own credentials without a human opening the dashboard. Each key carries a name, its scopes, an optional expiry, an optional list of allowed IPs, and an optional per-key rate-limit override. The override is self-service in one direction only: you can set a key below the default of 120 req/min, but raising a key above the default is done by Proxio support. The dashboard table also shows each key's prefix, when it expires, its allowed IPs, and a Last used timestamp so you can spot idle or stale keys.

Scopes

Every key carries one or more scopes. Each endpoint declares exactly one scope it requires, and the key must literally contain it, there is no implicit elevation from write to read.

The dashboard offers three presets when you create a key:

• Read-only = read
• Automation = read, write
• Full = read, write, purchase

If a key is missing the scope an endpoint needs, the request fails with INSUFFICIENT_SCOPE (403) and a details array naming the required scope:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key is missing the required scope.",
    "doc_url": "https://docs.proxio.net/docs/api/errors#insufficient_scope",
    "request_id": "req_8Ke2jP4mQ",
    "details": [{ "required": "purchase" }]
  }
}

IP allowlists

Each key can pin the source IPs that are allowed to use it. Store a list of CIDR ranges on the key; a call from an IP outside every range fails with IP_NOT_ALLOWED (403). Leave the list empty to allow any IP.

The IP that is checked is the public source address Proxio sees for the request. Allowlists pair well with server-to-server integrations that run from a stable set of egress IPs.

Expiry

A key can carry an expires_at timestamp. After it passes, the key stops working and calls fail with EXPIRED_API_KEY (401). Short-lived keys are a good fit for time-boxed jobs and contractors. Leave expires_at unset for a key that never expires on its own.

How a request is authenticated

On every call the API runs these checks in order and returns the first failure:

A malformed key and an unknown key both return INVALID_API_KEY with the same HTTP status and error code (the message text itself differs slightly, "the provided API key is malformed" versus "...is invalid"), so the API never reveals whether a given prefix exists.

Rotating keys

Because a key is scoped and independent, rotation is a clean, zero-downtime swap:

Related pages