Village Gateway API: your first decision
The steps a developer follows to ask Village Gateway for a decision, and to carry out the action only once it is allowed. This reference is in English; every route and field below is read from the code that runs.
Ask for evaluation access Read the step-by-step guide Technical details
Before the first call
- The Village owner opens Village Gateway approvals in the Village and creates a key. The key is shown once, starts with
vk_, and is sent asAuthorization: Bearer vk_…. An agent key holdsgateway:decide(ask for decisions and permits) andgateway:read(read them back). The system that carries out the action holds a separate key withgateway:redeem. A key cannot be created with bothgateway:decideandgateway:redeem. - The owner grants the key an authority: which action, on which resource, up to what amount and until when. A request outside every authority is denied.
- The person who created the key cannot approve a request made under it. A second person, a moderator of the Village, approves held requests.
The Village's own address is the host: https://YOUR-VILLAGE.mysovereignty.digital. The Village, the agent and the owner are never named in the request body; they come from the key.
Ask for a decision
POST /api/v1/gateway/decisions, with scope gateway:decide. Send an Idempotency-Key header of 8 to 64 characters (letters, digits and . _ : -); repeating a request with the same key and the same body returns the same decision.
curl -X POST https://YOUR-VILLAGE.mysovereignty.digital/api/v1/gateway/decisions \
-H "Authorization: Bearer vk_YOUR_KEY" \
-H "Idempotency-Key: pay-2026-11-0001" \
-H "Content-Type: application/json" \
-d '{"action":{"type":"payment.transfer","resource":{"kind":"account","ref":"acc-1042"},"amount":12500,"currency":"NZD","reversible":0,"payload_sha256":"cd1126fdd1aaeb2198d2012f32edc0141c49b5ee20eff8246ca1ce48976f3bd4"}}'
The body, formatted:
{
"action": {
"type": "payment.transfer",
"resource": {
"kind": "account",
"ref": "acc-1042"
},
"amount": 12500,
"currency": "NZD",
"reversible": 0,
"payload_sha256": "cd1126fdd1aaeb2198d2012f32edc0141c49b5ee20eff8246ca1ce48976f3bd4"
}
}
| Field | Rule |
|---|---|
type | Required. What the agent wants to do, for example payment.transfer. The start of the type decides which category governs it (see below). Every text field is at most 256 characters and is screened: control characters, most invisible formatting characters (zero-width space, soft hyphen, byte-order mark, left-to-right and right-to-left controls), surrogates, private-use characters and the line and paragraph separators are refused; the zero-width joiner and non-joiner are allowed. |
resource | Required. { kind, ref }, both non-empty text: what the action acts on. |
reversible | Required. The integer 0 or 1, not a boolean. |
payload_sha256 | Required. 64 lowercase hex characters: the SHA-256 of the payload the action will carry out. Village Gateway records the hash and never receives the payload. The example above is the hash of {"to":"acc-0077","amount":12500,"currency":"NZD"}. |
amount, currency | Optional pair. amount is a non-negative whole number in the smallest unit of the currency (12500 is 125.00 in a currency with two decimal places); currency is three upper-case letters and is allowed only with amount. |
operation, destination, asset, expires_at, unique_id, mandate_version | Optional. Text (mandate_version may also be a non-negative integer). |
An optional context object may carry category_id (3 to 48 characters: a lower-case letter, then lower-case letters, digits or underscores), category_version (text, or a whole number from 0, and it must match the version the Village holds for the category; sent without category_id, exactly one category must cover the action) and policy_profile_version (text, or a whole number from 0). A field that is not listed inside action, resource or context is refused; an unknown field at the top of the body is ignored. Any refusal of the body is the same answer, 400 invalid_request with the message The request was refused, so check the table above rather than looking for a hint in the reply.
Which category governs a request
A request joins a category when its action.type starts with one of the category's prefixes. The four starting categories are:
| Category | Action types that start with |
|---|---|
machine_intelligence_automation | agent. and automation. |
financial_records_transactions | payment. and invoice. |
governance_decisions_communications | resolution. and minutes. |
provenance_supply_chain_evidence | provenance. and lot. |
An action type that starts with none of these is judged under the Village's base policy only: it gets none of a category's rules and is not covered by a category's price. Use the prefixes above, or ask for a category of your own to be set up for the Village. The prefix is exact: payments.send does not start with payment..
The answer
A decision comes back with status 200 and these fields. decision is allow, gate (wait for a person to approve) or deny; state follows it. The receipt is the signed record of the decision.
{
"decision_id": "dec_…",
"commitment": "64 hex characters",
"decision": "gate",
"finding": "…",
"state": "pending",
"reason_codes": [
"APPROVAL_REQUIRED_BY_AUTHORITY"
],
"expires_at": "2026-11-12T20:00:00.000Z",
"receipt": {
"…": "the signed receipt"
},
"outcome": null
}
Read a decision back with GET /api/v1/gateway/decisions/:id (scope gateway:read). A key sees only its own decisions; any other id is 404 not_found. By default a held request waits up to 24 hours for approval, and an allowed decision is valid for 15 minutes.
Take a permit and act
When the decision allows the action (or a person has approved it), ask for a permit: POST /api/v1/gateway/decisions/:id/permits with { "audience": "name of the system that will act" } (1 to 256 characters), scope gateway:decide. The permit works once, for exactly that action, for 5 minutes by default.
The system that carries out the action holds the gateway:redeem key and checks the permit before it acts:
POST /api/v1/gateway/permits/redeemwith{ permit, audience, expectedCommitment }.expectedCommitmentis the 64-character commitment the system works out itself for the action it is about to perform, so a permit cannot be used for a different action. The reference program shows how; it is available on request.POST /api/v1/gateway/decisions/:id/outcomewith{ permit, audience, outcome }whereoutcomeisexecuted,failedoruncertain. The outcome joins the record.
Export the record and check it
GET /api/v1/gateway/decisions/:id/export(scopegateway:read, the key that asked): the decision, its approvals, the receipt and the events, signed as a whole.GET /api/v1/gateway/trust-bundle(scopegateway:read): the Village's public verification keys, in the format the checking program reads.- Then run the checking program offline, with no account and no network: the checking program, its published SHA-256 and the steps.
Errors
An error raised by the service is { "error": { "code": …, "message": … } } with a fixed message per code: nothing from below reaches the caller. A plain 404 (no such decision for this key, a path that does not exist, a Village that has no Village Gateway) is the shorter { "error": "Not found" }, with no code, so test the status first.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request, idempotency_key_required, permit_invalid | The body or the header is not as described above, or the permit was refused. |
| 401 | api_key_required, invalid_api_key, api_key_expired | No key, a key the Village does not know (a revoked key is refused too), or a key past its end date. |
| 403 | forbidden, entitlement_required, tenant_mismatch | The key lacks the scope, the person who made the key is no longer an owner or moderator of the Village, the category has not been added to this Village, or (tenant_mismatch) the key belongs to a different Village. |
| 404 | not_found (or the plain Not found body above) | No such decision for this key, or an unknown permit. The same answer comes from a Village that has no Village Gateway. |
| 409 | conflict, gateway_stopped, period_limit_exceeded | The request conflicts with an earlier one or with the state of the decision, the owner has stopped Village Gateway, or a spending limit would be exceeded. |
| 413 | payload_too_large | The body is over 64 KB. |
| 429 | no code | A request limit answered with plain text fields, { "error": "Too many requests…", "message": … }. Calls that carry a key (a bearer value starting with vk_ followed by at least 16 letters, digits, hyphens or underscores) are limited to 1200 a minute from one address; calls without one are limited to 300 a minute. Wait a moment and try again; the standard rate-limit headers carry the timing. |
| 500 | internal_error, authentication_error | Something failed on our side; nothing about it is shown. |
| 503 | unavailable | Nothing was recorded; try again. |
From an AI agent framework (MCP)
The same decisions are reachable through an MCP adapter at /mcp/village-gateway on the Village's address, with three tools: gateway_decide (scope gateway:decide), gateway_get_decision (scope gateway:read) and gateway_issue_permit (scope gateway:decide). It never approves a request, never redeems a permit and never reports an outcome: those stay with people and with the system that acts. No agent framework has used the adapter outside our own tests.
What this does and does not cover
Village Gateway decides on the requests it receives, records each decision as a signed receipt and issues a single-use permit for an allowed action. An action stops without a permit only at a system that checks for one before it acts; the reference program shows that check, and we have not connected a customer's own system to it. Evaluation access is issued by hand: ask for it here.