Go to developer

Verification & Consume

Challenge approval is not login complete. Your backend must consume the verification token, then create your session.

On this page

Security boundary

Challenge status: approved
         │
         │  verificationToken (returned once on poll)
         ▼
consumeChallenge(challengeId, verificationToken)
         │
         ▼
{ consumed: true, identityId }
         │
         ▼
YOUR application creates its own session
(KEYRA does not create your app session)

Consume the token

SERVERTypeScript
const approved = await keyra.waitForChallengeApproval(challengeId);
if (!approved.verificationToken) {
  throw new Error("verificationToken missing");
}

const result = await keyra.consumeChallenge(
  challengeId,
  approved.verificationToken,
);

if (result.consumed) {
  // Create YOUR session for the user bound to externalUserId / result.identityId
}

What happens here? KEYRA validates the token, marks it consumed, sets challenge status to consumed, and returns the linked identityId. Your product authorization starts only after this succeeds.

RESTHTTP
POST /v1/auth/challenge/{challengeId}/consume
Authorization: Bearer {clientId}:{clientSecret}
Content-Type: application/json

{ "verificationToken": "…" }

Consume response

responseResponse
JSON
{
  "consumed": true,
  "challengeId": "…",
  "identityId": "kid_…"
}
FieldTypeDescription
consumedbooleanWhether consume succeeded.
challengeIdstringThe challenge that was finalized.
identityIdstring | nullKEYRA identity id for the enrolled user.

Lifetime, single-use, replay

  • Token TTL ≈ 60s after approval — expired → HTTP 401 expired.
  • Second consume → HTTP 409 already_consumed.
  • Wrong token → HTTP 401 invalid_token.
  • Do not log raw verification tokens.

Create your application session

SERVER · exampleTypeScript
// After result.consumed === true:
// - Bind the session to YOUR user record (externalUserId you already authenticated)
// - Set cookie / issue JWT / establish server session per YOUR stack
// - Do not invent a KEYRA session cookie for Partner 2FA — KEYRA does not provide one here

res.setHeader("Set-Cookie", yourSessionCookie);
res.json({ ok: true });