authorize API
The authorize API
One HTTP call stands between your agent and every spend. Authenticate with the riv_ key, send the transaction, get a deterministic decision back — no SDK required.
POST /api/v1/authorize
Authorize a transaction
POST the amount and currency to /api/v1/authorize. Riv runs your active policies and answers allow, block or require_approval — every call lands in the ledger with an activityId.
bash
curl -X POST riventa.dev/api/v1/authorize \
-H "Authorization: Bearer riv_..." \
-d '{"amount":5,"currency":"USD"}'
// → { decision: "allow", reason, activityId }
Request body
- amountnumber
- transaction value, greater than 0, up to 2 decimals
- currencystring
- currency code, e.g. BRL or USD
- descriptionstring?
- optional — description kept for audit
- categorystring?
- optional — spend category; per-category mandates match on this
Response
200 OK
{
"decision": "allow",
"reason": "within monthly cap",
"activityId": "a1b2c3…"
}
block and require_approval are valid decisions, not errors. Only a real failure — invalid credential (401) or malformed input (400) — returns an error field.
GET /api/v1/activities
Read the ledger
GET /api/v1/activities returns the agent's recent statement, or a single record with ?id=. Same Bearer riv_ auth as authorize.
agent · descriptionamount · status
pay-agentopenai api
$5.00 approved
research-botserp api
$8.00 blocked
ops-agenttwilio sms
$3.00 approved
data-agentsnowflake
$12.00 pending
pay-agentanthropic
$4.00 approved