Authentication Model
How Cresora authenticates API requests using Bearer tokens and the three-tier hierarchy.
Cresora uses Bearer token authentication. Every API request must include your API key in the Authorization header.
Request format
Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxxNo other authentication schemes (OAuth, cookies, API key query params) are supported.
Three-tier hierarchy
Cresora's access model follows three tiers:
Platform (Cresora Commerce)
└── Partner (your ISV account)
└── Merchant (sub-merchants you onboard)Your API key is scoped to the Partner tier. When you create a payment, you specify which merchant the payment belongs to via merchant_id. You can only interact with merchants under your own partner account.
What a request looks like end-to-end
curl -X POST https://api.cresoracommerce.ai/api/v1/transactions \
-H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_$(uuidgen)" \
-d '{
"type": "SALE",
"merchant_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
"amount": "50.00",
"currency": "USD",
"vault_token": "cvt_01885fec-4444-7a31-9bbb-3e5b9a1f8c42",
"use_type": "ONE_TIME_FUTURE"
}'- The
Authorizationheader identifies your Partner account - The
merchant_id— a UUID — scopes the payment to one of your merchants - The
vault_tokenidentifies the saved card to charge. Raw card numbers are never accepted here: a card is first captured through a hosted-page save-card flow, which vaults it and returns thecvt_…reference - The
use_typedeclares reuse intent and drives the network CIT/MIT classification —ONE_TIME_FUTUREis a cardholder-initiated charge - The host you call selects the environment (sandbox vs. production)
To check only that your key works — no merchant, no payment instrument — call
GET /partner/me instead. This example shows
the full shape of a charge, which needs a vaulted card first.
Error responses
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Key missing, malformed, expired, or rotated |
403 | unauthorized | Key is valid but not permitted for this endpoint — the default 403 code |
403 | feature_not_enabled | Endpoint requires a feature flag not on your key |
404 | merchant_not_found | Key is valid, but merchant_id is not under your partner account |
Branch on the status, not on the code. unauthorized is the only code that
appears on two statuses: 401 means the credential itself was rejected, 403
means the credential was accepted but the caller is not permitted. An individual
authorization guard may narrow the 403 to a more specific code, so treat the
code as a refinement and the status as the contract.
A merchant_id that is not yours returns 404, not 403 — the same code you
would get for a merchant that does not exist, so that a probe cannot distinguish
"not yours" from "not real".