Create an approval request (intents API)

A system creates a request (intent) so that a person approves or declines one specific operation. The person sees the exact values and decides with a passkey or, when the type allows it, on their phone.

The request

curl -sS -X POST https://identity.example.com/v1/intents \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-INV-42-attempt-1" \
  -d '{"operationType":"invoice.pay","subjectEmail":"ana@example.com",
       "externalReference":"INV-42","expiresInSeconds":900,
       "fields":{"amount":{"amount":"1250.00","currency":"EUR"}}}'

• Name the person with exactly one of subjectUserId or subjectEmail.
• Idempotency-Key is required: 1 to 256 visible ASCII characters, unique per operation on your side.
• Values: strings for text, integer, decimal and date (no floats), JSON booleans, {"amount","currency"} for money and the option key for choices.

The answer

• 201 with Location on the first creation.
• 200 with Idempotent-Replayed: true when you repeat with the same key and body.
• 409 with the same key and a different body.
• The body carries intentJson (the document the person sees), intentDigest and comparisonCode.

Show the comparison code

In typed mode (the default), the phone hides the code and the person types the six digits of comparisonCode. Your application must show comparisonCode next to the operation, or the person cannot approve on the phone.

Retries

Retry on network errors, 429 and 5xx with the same key and exponential backoff. Never generate a new key for the same operation.

Limits

Lifetime from 60 seconds up to the type's maximum (default 900 s, at most 24 h). At most 20 pending requests per person and 1,000 per client; the next one gets 429.

Personal data

Do not put more personal data in the fields or in externalReference than the approval needs.