ShieldAuthorization

Request spending authority

POST
/v1/shield/authorize

Returns ALLOW, ASK, or BLOCK for one proposed spending action.

Authorization

shieldApiKey
AuthorizationBearer <token>

In: header

Header Parameters

X-Shield-App-Id*string

Registered integration identity. The server resolves trusted display metadata.

Length3 <= length <= 120
X-Shield-Environment*string

Value in

  • "sandbox"
  • "production"
Idempotency-Key?string
Length8 <= length <= 180

Request Body

application/json

amount*number

Major currency units, for example 89.00 USD.

Range0 < value
currency*string

ISO 4217 currency code.

Match^[A-Z]{3}$
purpose*string

Clear user-facing reason for spending.

Length3 <= length <= 240
merchant?string
Length1 <= length <= 160
category?string
Length1 <= length <= 80
agentId?string

Stable identity for the agent acting inside the registered application.

Length1 <= length <= 120
transactionType?string
Default"PURCHASE"

Value in

  • "PURCHASE"
  • "SUBSCRIPTION"
  • "RENEWAL"
  • "TRANSFER"
  • "REFUND"
  • "OTHER"
metadata?

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/shield/authorize" \  -H "X-Shield-App-Id: string" \  -H "X-Shield-Environment: sandbox" \  -H "Content-Type: application/json" \  -d '{    "amount": 89,    "currency": "USD",    "purpose": "Book hotel",    "merchant": "Hilton",    "category": "travel",    "agentId": "travel-agent",    "transactionType": "PURCHASE"  }'
{  "verdict": "ALLOW",  "allowed": true,  "approvalRequired": true,  "approvalStatus": "NOT_REQUIRED",  "reason": "string",  "reasonCode": "string",  "requestId": "string",  "decisionId": "string",  "dossierId": "string",  "environment": "sandbox",  "advanced": {    "policyVersion": "string",    "reasonCodes": [      "string"    ],    "evidenceHash": "string",    "signatures": {},    "evaluationMetadata": {}  }}