Pass verification

Send the Pass Token read from a customer's wallet pass. The server looks the token up, checks the pass and the age requirement, records a transaction and gives the customer's wallet a fresh token.

curl -X POST https://abyrgverslun.is/api/v1/verifications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pass",
    "passData": "22V6MKRDAVZDP0Q9K0ACD7DSB5JAKZ5R1G86M60YKWPH0G2RHQJZS",
    "requiredAge": 20,
    "posReference": "till4-1234"
  }'

# $DPOP_PROOF is a fresh proof for POST https://abyrgverslun.is/api/v1/verifications
curl -X POST https://abyrgverslun.is/api/v1/verifications \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pass",
    "passData": "22V6MKRDAVZDP0Q9K0ACD7DSB5JAKZ5R1G86M60YKWPH0G2RHQJZS",
    "requiredAge": 20
  }'

const response = await fetch('https://abyrgverslun.is/api/v1/verifications', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    method: 'pass',
    passData: scannedValue, // exactly as read from the QR code or NFC
    requiredAge: 20,
  }),
});

if (response.status === 429) {
  const retryAfter = Number(response.headers.get('Retry-After'));
  // Wait retryAfter seconds before trying again
} else if (response.ok) {
  const { result, reason, transactionId } = await response.json();
  // result: 'pass' | 'fail'
  // reason (fail only): 'invalid' | 'unknown' | 'expired' | 'consumed'
}

// Age requirement met
{
  "result": "pass",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "livemode": true
}

// Valid pass, but the customer is under requiredAge (no reason)
{
  "result": "fail",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "livemode": true
}

// Token refused
{
  "result": "fail",
  "transactionId": "k1jcce4akgxtehpqa9pz2809dnxpxhfq",
  "reason": "consumed",
  "livemode": true
}

// Not a Pass Token: no transaction is recorded
{
  "result": "fail",
  "reason": "invalid",
  "livemode": true
}

Fail reasons

reason is only present when the token itself was refused. An underage customer gets "result": "fail" with no reason.

Errors

Errors use Problem Details (application/problem+json). See Errors for the full format.

A 429 carries a Retry-After header in seconds, and the body repeats it as retryAfterSeconds with "reason": "rate_limited". The limits are on the Rate limits page.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12

{
  "retryAfterSeconds": 12,
  "reason": "rate_limited",
  "livemode": true,
  "type": "https://api.aldursvottun.is/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded, retry after 12 second(s)"
}

Retrying safely

A verification consumes the Pass Token, so retrying one whose response you lost would answer consumed. Send an Idempotency-Key header (a fresh UUID per verification) and reuse it on every retry of that verification:

• A retry with the same key and the same body within 24 hours returns the original response with the header Idempotent-Replayed: true. Nothing is consumed or recorded again, and it does not count toward the rate limit.
• Keys belong to the caller: your service client or device in your tenant. Another caller's key never returns your result.
• The same key with a different body gives 422 with type idempotency-key-reused. Use a new key for a new verification.
• Responses that recorded nothing (invalid, a 429 or another error) are not stored. A retry with the same key runs again.
• Duplicate requests sent at the same time are safe too: one runs and the other gets its result.

Without a key, recover a lost response by looking it up with GET /api/v1/transactions?posReference=.

Looking up a result later

GET /api/v1/verifications/{transactionId} returns { "id", "status": "completed", "result", "transactionId" } for a recorded pass verification. It takes the same callers and scope as the POST. See eID verification for the endpoint.