PovitoDevelopers
العربية

Keys and environments#

Every public Povito API has two environments:

  • Sandbox — for building and testing, with test keys. No real money, stock or customers.
  • Live — production, with live keys.

Every request carries its key as a bearer token, Authorization: Bearer <key>. A key is shown once, when it is issued, and Povito stores only a hash of its secret — nobody, including Povito support, can read it back. Keep it out of repositories and client-side code.

Base URLs#

API Sandbox Live
Partner API https://api-staging.povito.com/partner/v1 https://api.povito.com/partner/v1
Checkout API https://api.checkout.staging.povito.com/v1 https://api.checkout.povito.com/v1
Checkout hosted page https://checkout.staging.povito.com https://checkout.povito.com

The OpenAPI contracts list the Checkout Sandbox server as Staging; it is the same host.

Before Povito launches

Build and test against the Sandbox. The Live environments open at launch. Until then https://api.povito.com is served by the Sandbox — it accepts test keys and refuses live ones — and the Checkout Live host does not exist yet. Nothing changes in your integration at launch except the base URL and the key.

Key formats#

API Key Test Live Issued by Where it may live
Partner API secret povito_sk_test_… povito_sk_live_… the seller, in the Seller dashboard → Settings → Integrations the server or integration that calls the API
Checkout API secret povito_ck_test_… povito_ck_live_… Povito, to the merchant your server only
Checkout API publishable povito_pk_test_… povito_pk_live_… Povito, to the merchant a browser or app — it unlocks only /v1/public/*

Each key has the shape <prefix>_<mode>_<key_id>_<secret>; treat the whole string as opaque.

Where each key is accepted#

The two APIs draw the line between test and live in different places. Read the one you are integrating.

Partner API: the environment decides#

  • A test key works only in the Sandbox; a live key works only in Live. Sent to the other environment, a key is refused with 401 — code api_key_wrong_environment, with a message that says which environment the key belongs to.
  • Each environment issues its own keys, from the Seller dashboard of the seller account you integrate: a Sandbox seller account issues test keys, a Live seller account issues live keys. Povito creates Sandbox seller accounts on request — ask your Povito contact. They stay unapproved, so nothing they sync is shown to shoppers.
  • The Sandbox has no real money, stock or customers, so nothing a test sync does reaches a shopper.
  • A key belongs to exactly one seller account and carries the scopes chosen when it was created — see authentication and scopes.

Checkout API: test mode is a key mode#

On the Checkout API the key's mode, not the host, decides whether a call is a test. A povito_ck_test_… key is accepted by the Live base URL, https://api.checkout.povito.com/v1, as well as by the Sandbox — you do not need the Sandbox host to test. Whatever a test key does is in test mode:

  • the objects it creates carry livemode: false, never touch money, and never share a row with live objects;
  • the simulated test payment method can be offered — it is refused outright in live mode — and the test phone +9647500000000 receives the code 000000 with no SMS sent;
  • it cannot see live objects (404, never a hint that they exist) and cannot register a live webhook endpoint (403 mode_mismatch), and a live key is held to the same rules the other way round.

A povito_ck_live_… key on the Live host takes real money. The Sandbox host is a separate deployment with its own merchants and keys: a key is recognised only by the deployment that issued it (anywhere else it is 401 invalid_api_key), so ask Povito for keys for the host you will call. The full test toolkit — the simulated gateway, amount-driven outcomes, vendor sandboxes — is in Testing.

Side by side#

Partner API Checkout API
What makes a call a test The environment (base URL) The key's mode
A test key on the Live base URL Refused — 401 api_key_wrong_environment Accepted, in test mode (if Live issued it)
A live key on the Sandbox base URL Refused — 401 api_key_wrong_environment Not recognised — 401 invalid_api_key
Who issues keys The seller, in the Seller dashboard Povito
Scopes catalog:read, catalog:write, inventory:write, orders:read, webhooks:manage sessions:write, sessions:read, refunds:write, refunds:read, webhooks:manage, events:read, customers:read
Missing, malformed or revoked key 401 invalid_api_key 401 invalid_api_key (invalid_publishable_key on /public/*)
Key without the scope a route needs 403 insufficient_scope 403 insufficient_scope
Revoking In the Seller dashboard; takes effect on the next request Ask Povito; rotation issues a second key and both work until you revoke the old one

Every error both APIs can return: Errors. Key hygiene: Security.