Resolve which engine owns a key

Authoritative, never advisory. 200 resolved:true names the owning engine; 200 resolved:false is a decided negative — nobody’s key, or another tenant’s, indistinguishably; 503 means the Courier cannot answer and the caller fails the payment closed. This operation never answers 404. A POST that reads: the key is personal data and travels in the body, never in a URL. An engine treats ANY status other than 200 and 422 as fail-closed — 404, 405, 429 and every 5xx included — and keys on the code (JDC-9001), never on the detail sentence. The 503 sentence names what could not answer — the ownership map, or the engine credential (registry or tenant database) — and both tell the engine to fail closed.

POST /v1/ownership/lookup

Resolve which engine owns a key

cURL

curl --request POST \
  --url https://api.example.com/v1/ownership/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "<string>",
  "branch": "<string>",
  "keyValue": "<string>"
}
'

200

{
  "keyKind": "ACCOUNT",
  "keyValue": "<string>",
  "resolved": true,
  "resolvedAt": "2023-11-07T05:31:56Z",
  "source": "ASSIGNMENT_MAP",
  "engineId": "<string>",
  "ownedByCaller": true
}

Autorizaciones

Authorization · string · header · requerido

An Access Manager application token whose subject is bound to exactly one engine; an engine may hold several, one per calling product. It reaches only the operations its scopes name; the operator surface refuses it.

Scopes

ownership:read

Read the ownership map

Cuerpo

application/json

keyKind · enum<string> · requerido

The kind of key.

Opciones disponibles: ACCOUNT, DOCUMENT, PIX_KEY_EMAIL, PIX_KEY_PHONE, PIX_KEY_RANDOM, PAYMENT_ID, PIX_RECURRENCE_ID, PIX_RECURRENCE_ID_CHARGER

account · string

ACCOUNT only: the account number, digits with an optional trailing check-digit letter.

Maximum string length: 256

branch · string

ACCOUNT only: a current account's branch, 1 to 4 digits. Omit it, or send it empty, for a payment account, which has none; empty is never branch 0.

Maximum string length: 256

keyValue · string

The key as the caller holds it, for every kind except ACCOUNT. Do not pre-normalize.

Required string length: 1 - 256

Respuesta

200

application/json

OK

keyKind · enum<string> · requerido

Opciones disponibles: ACCOUNT, DOCUMENT, PIX_KEY_EMAIL, PIX_KEY_PHONE, PIX_KEY_RANDOM, PAYMENT_ID, PIX_RECURRENCE_ID, PIX_RECURRENCE_ID_CHARGER

keyValue · string · requerido

The normalized form the Courier resolved against.

Maximum string length: 256

resolved · boolean · requerido

resolvedAt · string<date-time> · requerido

source · enum<string> · requerido

Opciones disponibles: ASSIGNMENT_MAP

engineId · string

Present only when resolved is true.

ownedByCaller · boolean

Present only when resolved is true: whether the owner is the engine whose credential made this call. Compare on this; an engine never needs its own registry id.