V1.2 Passkeys

Add passkeys to a V1.2 REST integration without replacing your OTP flow. Your backend starts authentication, Akedly hosts the WebAuthn ceremony, and your app falls back to OTP whenever passkey authentication is unavailable or unverified.

Before you start: passkeys must be enabled

Every endpoint on this page returns 403 PASSKEY_DISABLED until all three of these are true:

You can integrate against this page before any of them is on: every call simply returns 403 PASSKEY_DISABLED and your OTP fallback runs, so the passkey path lights up with no further code changes once all three are true.

Passkey or OTP

There is no passkey lookup endpoint. Use POST /auth-options as the availability check:

1. Solve the same Proof-of-Work challenge used by the V1.2 OTP flow. Obtain a Turnstile token when the pipeline requires one.
2. Call POST /api/v1.2/transactions/passkey/auth-options.
3. On 200, open the hosted ceremony with the returned ceremonyToken.
4. On 404 with code: "NO_PASSKEY", continue with your existing OTP send and verify flow.
5. On 403 with code: "PASSKEY_DISABLED", continue with OTP. It is a safe fallback and a configuration signal: passkeys are off at one of the three gates above and the response does not tell you which — one code covers all of them. If you get it on every call, check all three in Before you start rather than your integration. For passkey-specific 429 responses, honor retryAfter and offer a user-initiated OTP option rather than triggering the paid fallback automatically. Apply your normal retry or failure policy to configuration, circuit-breaker, and invalid-proof errors.

const response = await fetch(
  'https://api.akedly.io/api/v1.2/transactions/passkey/auth-options',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      APIKey: process.env.AKEDLY_API_KEY,
      pipelineID: process.env.AKEDLY_PIPELINE_ID,
      verificationAddress: { phoneNumber },
      powSolution,
      turnstileToken,
      returnTarget: { origin: 'https://your-site.example' },
    }),
  }
)

const body = await response.json()
if (response.status === 404 && body.code === 'NO_PASSKEY') {
  return startOtpFlow(phoneNumber)
}
if (!response.ok) throw new Error(body.code)

// Keep requestID with the user/sign-in you started. The result proof is bound to it.
return {
  ceremonyToken: body.data.ceremonyToken,
  requestID: body.data.requestID,
}

Endpoint reference

Base URL:

https://api.akedly.io/api/v1.2/transactions/passkey

Authentication endpoints

Start authentication

POST /auth-options runs the API-key, circuit-breaker, passkey-rate-limit, Turnstile, and PoW middleware before it checks for a credential.

{
  "APIKey": "YOUR_API_KEY",
  "pipelineID": "YOUR_PIPELINE_ID",
  "verificationAddress": {
    "phoneNumber": "+201234567890"
  },
  "powSolution": {
    "challengeToken": "SIGNED_CHALLENGE_TOKEN",
    "nonce": 42
  },
  "turnstileToken": "TURNSTILE_TOKEN",
  "returnTarget": {
    "origin": "https://your-site.example"
  }
}

{
  "status": "success",
  "data": {
    "ceremonyToken": "pk1.<encrypted-token>",
    "requestID": "8ca6bb40-c01f-4dc7-a704-45d1d950a024",
    "options": {
      "challenge": "<base64url>",
      "rpId": "akedly.io",
      "timeout": 60000,
      "userVerification": "required",
      "allowCredentials": [
        {
          "id": "<credential-id>",
          "transports": ["internal"],
          "type": "public-key"
        }
      ]
    }
  },
  "message": "Passkey authentication initiated"
}

Verify authentication

POST /auth-verify burns the ceremony token, verifies the WebAuthn assertion with user verification required, settles the passkey charge, and returns signed proof.

{
  "ceremonyToken": "pk1.<encrypted-token>",
  "authResp": {
    "id": "<credential-id>",
    "rawId": "<credential-id>",
    "response": {
      "authenticatorData": "<base64url>",
      "clientDataJSON": "<base64url>",
      "signature": "<base64url>",
      "userHandle": null
    },
    "type": "public-key"
  }
}

{
  "status": "success",
  "data": {
    "verified": true,
    "transactionID": "8ca6bb40-c01f-4dc7-a704-45d1d950a024",
    "frontendCallbackURL": "https://your-site.example/auth/callback?transactionID=8ca6bb40-c01f-4dc7-a704-45d1d950a024&status=Successful",
    "resultToken": "pkrt1.<payload>.<hmac>"
  },
  "message": "Passkey verified successfully"
}

{
  "status": "error",
  "code": "PASSKEY_AUTH_FAILED",
  "message": "Assertion did not verify",
  "data": {
    "frontendCallbackURL": "https://your-site.example/auth/callback?transactionID=8ca6bb40-c01f-4dc7-a704-45d1d950a024&status=Failed&reason=passkey_auth_failed"
  }
}

For terminal PASSKEY_AUTH_FAILED, INSUFFICIENT_QUOTA, and BILLING_FAILED errors with ceremony context, data.frontendCallbackURL contains the failed redirect URL when the pipeline configures one; otherwise it is null. The idempotency-loser path explicitly skips callback dispatch and returns the error envelope without data. When present, the URL's reason query value is the lowercased error code.

Enrollment endpoints

Create registration options

POST /register-options accepts the enrollmentToken returned by a successful V1.2 OTP /verify. The underlying OTP verification must still be successful, unused for enrollment, and within the 120-second enrollment window.

{
  "enrollmentToken": "pk1e.<encrypted-token>",
  "returnTarget": {
    "url": "myapp://akedly-passkey"
  }
}

{
  "status": "success",
  "data": {
    "ceremonyToken": "pk1.<encrypted-token>",
    "options": {
      "challenge": "<base64url>",
      "rp": {
        "id": "akedly.io",
        "name": "Akedly"
      },
      "user": {
        "id": "<opaque-user-handle>",
        "name": "Your company (+201****7890)",
        "displayName": "Your company — +201****7890"
      },
      "pubKeyCredParams": [
        { "alg": -8, "type": "public-key" },
        { "alg": -7, "type": "public-key" },
        { "alg": -257, "type": "public-key" }
      ],
      "timeout": 60000,
      "attestation": "none",
      "excludeCredentials": [],
      "authenticatorSelection": {
        "residentKey": "discouraged",
        "userVerification": "required",
        "requireResidentKey": false
      },
      "extensions": {
        "credProps": true
      },
      "hints": []
    }
  },
  "message": "Passkey enrollment initiated"
}

Verify registration

POST /register-verify burns the enroll ceremony token, requires user verification, consumes the OTP verification's single enrollment right, and stores the credential.

{
  "ceremonyToken": "pk1.<encrypted-token>",
  "attResp": {
    "id": "<credential-id>",
    "rawId": "<credential-id>",
    "response": {
      "attestationObject": "<base64url>",
      "clientDataJSON": "<base64url>",
      "transports": ["internal"]
    },
    "type": "public-key"
  },
  "deviceLabel": "Sara's phone"
}

{
  "status": "success",
  "data": {
    "enrolled": true,
    "credentialId": "<credential-id>",
    "deviceLabel": "Sara's phone",
    "resultToken": "pkrt1.<payload>.<hmac>"
  },
  "message": "Passkey enrolled successfully"
}

Hosted page endpoints

Resolve ceremony

GET /ceremony?token=... is read-only and never burns the token. It accepts an enrollment token or ceremony token.

{
  "status": "success",
  "data": {
    "purpose": "auth",
    "branding": {
      "logo": null,
      "companyName": "Your company",
      "primaryColor": "#008081",
      "secondaryColor": "#ABD1D1",
      "theme": "light"
    },
    "phoneNumber": "+201****7890",
    "returnTarget": {
      "origin": "https://your-site.example"
    },
    "options": {
      "challenge": "<base64url>",
      "rpId": "akedly.io",
      "timeout": 60000,
      "userVerification": "required",
      "allowCredentials": [
        {
          "id": "<credential-id>",
          "type": "public-key",
          "transports": ["internal"]
        }
      ]
    }
  }
}

Read authentication result

GET /result?token=... is a read-only recovery poll for auth ceremonies. It accepts an already-burned auth ceremony token and never burns it. It never returns or remints a resultToken. When it recovers state: "verified" after the hosted page loses the verify response, the page returns verified: false, code: "no_proof", and the transaction ID; confirm that transaction through your backend record or callback before falling back to OTP. Normal token expiry returns 410 PASSKEY_TOKEN_EXPIRED. The 200 response with state: "expired" is reserved for a missing auth-request row while the token is still fresh.

{
  "status": "success",
  "data": {
    "state": "verified",
    "transactionID": "8ca6bb40-c01f-4dc7-a704-45d1d950a024",
    "verified": true,
    "isTest": false,
    "frontendCallbackURL": "https://your-site.example/auth/callback?transactionID=8ca6bb40-c01f-4dc7-a704-45d1d950a024&status=Successful"
  }
}

Error reference

Every controller error uses:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Error description"
}

/auth-options can also return middleware errors with retry metadata.

POST /auth-options also inherits the V1.2 pipeline and Shield middleware:

PoW and Turnstile errors add retryable. Passkey rate-limit and circuit-breaker errors add retryable, retryAfter, cooldownSeconds, and details; retryAfter is an ISO timestamp and cooldownSeconds is the delay.

Results and validation

A successful passkey authentication has three result channels:

The browser relay and backend callback both fire for successful authentication when a callback is configured. Do not treat one channel as suppressing the other.

The passkey callback uses the V1.2 OTP-shaped envelope:

{
  "mainTransaction": {
    "transactionID": "8ca6bb40-c01f-4dc7-a704-45d1d950a024",
    "status": "Successful",
    "pipelineID": "YOUR_PIPELINE_ID",
    "verificationAddress": {
      "phoneNumber": "+201234567890"
    },
    "verificationMethod": "passkey",
    "isTest": false,
    "updateDate": "2026-07-29T12:00:00.000Z"
  },
  "transactionReq": {
    "status": "Successful",
    "verificationMethod": "passkey",
    "isTest": false,
    "verificationDate": "2026-07-29T12:00:00.000Z"
  }
}

mainTransaction.transactionID is the PasskeyAuthRequest.requestID UUID. It is not a MainTransaction.transactionID; the callback uses a synthetic OTP-compatible object because passkey authentication does not create a MainTransaction.

Terminal PASSKEY_AUTH_FAILED, INSUFFICIENT_QUOTA, and BILLING_FAILED outcomes send the same envelope with status: "Failed". A successful idempotent replay does not send a duplicate callback.

Verify resultToken

The token payload is:

{
  "v": 1,
  "purpose": "auth",
  "transactionId": "8ca6bb40-c01f-4dc7-a704-45d1d950a024",
  "pipelineId": "YOUR_PIPELINE_ID",
  "verified": true,
  "iat": 1785326400000,
  "exp": 1785326520000
}

The signature is HMAC_SHA256("pkrt1." + base64url(payload), APIKey). iat and exp are milliseconds; the token expires after two minutes. Verify it on your backend with a constant-time signature comparison, require canonical unpadded base64url, check exp and verified, require purpose: "auth" and your own pipelineId, bind transactionId, and enforce single use.

const crypto = require('crypto')

function verifyResultToken(token, apiKey) {
  // Fail closed on an unusable key — see the callout above.
  if (!apiKey || typeof apiKey !== 'string') return null
  if (typeof token !== 'string' || !token.startsWith('pkrt1.')) return null

  const parts = token.slice('pkrt1.'.length).split('.')
  if (parts.length !== 2) return null
  const [payloadB64, sigB64] = parts

  // Strict unpadded base64url charset. Buffer.from(..,'base64url') is LENIENT and ignores
  // stray characters, which would admit alternate spellings of the same signed proof.
  const B64URL = /^[A-Za-z0-9_-]+$/
  if (!B64URL.test(payloadB64) || !B64URL.test(sigB64)) return null

  const given = Buffer.from(sigB64, 'base64url')
  const payloadBuf = Buffer.from(payloadB64, 'base64url')
  // Enforce CANONICAL encoding, not just the charset. A segment whose length is not a
  // multiple of 3 bytes has slack bits in its final character, so a DIFFERENT string can
  // decode to the SAME bytes. Your single-use check below is keyed on the token STRING, so
  // an alias would sail past it and replay a spent proof. Re-encode and require an exact match.
  if (given.toString('base64url') !== sigB64) return null
  if (payloadBuf.toString('base64url') !== payloadB64) return null

  const expected = crypto
    .createHmac('sha256', apiKey)
    .update(`pkrt1.${payloadB64}`)
    .digest()
  // Constant-time compare; timingSafeEqual throws on a length mismatch.
  if (given.length !== expected.length) return null
  if (!crypto.timingSafeEqual(given, expected)) return null

  const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'))
  if (payload.verified !== true) return null
  if (typeof payload.exp !== 'number' || Date.now() > payload.exp) return null

  // The HMAC key is your ACCOUNT API key, so a valid signature only proves the token
  // came from Akedly for YOUR account — not which pipeline it came from, and not that
  // it was an authentication at all. Both of the next two checks are required.
  if (payload.purpose !== 'auth') return null
  if (payload.pipelineId !== process.env.AKEDLY_PIPELINE_ID) return null

  // Still yours to do: bind payload.transactionId to the sign-in YOU started,
  // and enforce single use so a replayed token cannot mint a second session.
  return payload
}

Platform SDKs

• Web / JavaScript
• iOS / Swift
• Android / Kotlin
• Flutter / Dart
• React Native

Each SDK page covers only its launcher, return channel, and platform-specific outcomes. Keep the API key and resultToken verifier on your backend.