Skip to main content

Authentication

Every request to /api/v1/* (except Collect checkout) requires an API key in the Authorization header:

Authorization: Bearer vltro_live_xxxxxxxxxxxxxxxxxxxx

Create and revoke keys from Dashboard → API keys. Keys are shown once at creation — Veltro only stores a SHA-256 hash, never the raw key.

Scopes​

Each key carries one or more scopes, set at creation time:

ScopeGrants
readGET endpoints — list/read your own resources
writeread + POST endpoints — create payment links, invoices, payouts, etc.
admineverything, including endpoints that would otherwise require a specific higher scope

A key with only read will get a 403 on any POST endpoint.

Collect keys — a separate, narrower key type​

vltro_pk_... Collect keys are a different trust tier, meant to be embedded in public client-side code (a checkout widget on your own site). They:

  • only work against POST /api/v1/collect/checkout,
  • can never read account data or perform any other action,
  • are safe to expose in a browser bundle — a normal vltro_live_... server key is not.

Example​

curl https://veltro.online/api/v1/payment-links \
  -H "Authorization: Bearer vltro_live_xxxxxxxxxxxx"
const res = await fetch("https://veltro.online/api/v1/payment-links", {
  headers: { Authorization: `Bearer ${process.env.VELTRO_API_KEY}` },
});
const { data } = await res.json();

Never commit an API key to source control or expose a vltro_live_... key in client-side code — use a Collect key for that instead.