Skip to main content

Authentication

Every request is authenticated with an API key, sent as a Bearer token:

curl https://api.plustiveimpact.com/api/v1/balance \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxx"

Getting a key​

Create and manage keys from API keys in your dashboard. A key is shown once, at creation — store it securely. We only ever keep a hash and the non-secret prefix (pk_live_…).

Keeping keys safe​

  • Server-side only. Never embed a key in a browser, mobile app, or public repo — it can buy data from your wallet.
  • Rotate freely. Issue a new key, deploy it, then revoke the old one. Revocation is immediate.
  • One key per integration. Separate keys per server/environment make rotation and auditing painless.

IP allowlisting​

Alongside your API key, requests can be restricted to a set of approved server IPs — so a leaked key is useless from anywhere else. The allowlist is managed by Plustive: send us the public IPs (or CIDR ranges) your servers call from and we'll apply them, typically during onboarding.

  • Accounts created from July 2026 onward must have an allowlist configured before the API accepts requests.
  • Earlier accounts are unaffected until they opt in — ask us to enable it any time.

Both IPv4 and IPv6 are supported, as single addresses (203.0.113.9, 2606:4700::10) or ranges (203.0.113.0/24). If your servers egress over both IPv4 and IPv6, allowlist both — outbound calls may use either family.

Requests from an unapproved address are rejected with 403 Forbidden before anything else runs — a blocked purchase never charges your wallet:

{
  "title": "Request blocked by IP allowlist.",
  "status": 403,
  "errors": [{ "name": "ip.not_allowed", "reason": "Requests from 203.0.113.9 are not allowed for this account. Contact Plustive to update your IP allowlist." }]
}

The rejected address is echoed back, so you always know exactly which IP to ask us to add. If your account requires an allowlist and none is configured yet, you'll see ip.not_configured instead — send us your server IPs to get started.

For transparency, every purchase records the IP it was made from: it's shown per transaction on your monthly invoice CSV, and your invoice PDF includes a summary of the addresses your account purchased from that cycle.

Errors​

A missing or invalid key returns 401 Unauthorized. All errors use a consistent shape:

{
  "type": "https://www.rfc-editor.org/rfc/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key.",
  "errors": [{ "name": "generalErrors", "reason": "Invalid API key." }]
}

Read detail for a human-readable message; errors[].reason carries the same.