Decisions, challenges, and review

Every successful authorization response contains exactly one of four decisions. An HTTP success confirms that the decision was computed. Select the application path using the decision, mode, proof, and account permissions.

The Assurance Profile and reason codes explain the decision. Use the authorization decision to select the next application step.

Passkey registration and confirmation

Before using a passkey challenge, your backend may create a one-time registration grant for its authenticated subject with createPasskeyRegistrationGrant(subjectId). Send that grant only through your authenticated application flow and call observer.registerPasskey(grant.token) in the browser. Authorize grant issuance through your account-recovery and reauthentication rules for the signed-in subject.

For a returned challenge, obtain the saved pending intent from your authenticated backend along with the challenge ID. Present that immutable intent alongside the browser SDK's challenge details in an explicit confirmation callback:

const receipt = await observer.completeChallenge(challenge.id, {
  confirm: async (details) => {
    return showAndConfirmExactAction({
      intent: pendingIntent, // Saved by the backend for this pending request.
      assurance: details.display,
    });
  },
});

showAndConfirmExactAction is your application's accessible confirmation UI. GrayPass's details.display contains action and consequence information, audience, and resource/context digests. Display it alongside the exact destination and intent fields saved by your backend for that pending request. Use the immutable saved values throughout confirmation. Clearly name the operation and provide explicit confirm and cancel controls.

The browser receives a completion receipt identifying the resulting authorization. Your backend must fetch that authorization, associate it with the original pending request, and perform proof verification. Use the verified authorization and proof to determine execution. See Integration.

Sandbox confirmation

sandbox_confirm is a labeled integration-test method available only in sandbox when permitted by policy. Use it to simulate the confirmation step in an integration test. Use a passkey ceremony for authenticator-backed approval. To show a confirmation screen for this method, first fetch observer.challengeDetails(id) and display the backend’s saved intent. Only after the user confirms should you call observer.completeChallenge(id, { method: 'sandbox_confirm' }). This method uses your preceding confirmation UI; the confirm callback belongs to the passkey path.

Use Capabilities to check the supported challenge methods for your integration.

Expiry, cancellation, and changed requests

Challenges expire; the response includes expires_at. Treat cancellation, expiry, unavailable credentials, and failed ceremonies as non-execution. Request fresh authorization when necessary. If the user changes the business request, create a new logical request and authorization. Do not resume the old challenge with new parameters.

The challenge reruns the original authorization with the relevant detector and policy conditions preserved. Inspect the resulting child decision, including any continuing hold.

Manual review

A hold can be reviewed in Console Activity by a security reviewer, administrator, or owner. For API-based review, use an admin credential. The review operation records an attributed approve or reject resolution and may produce a child authorization. Fetch that child and apply the same independently stored action binding and proof requirements before execution. Preserve the original subject, account, resource, and destination throughout review.

Your organization must define who can review, what evidence the reviewer sees, when another channel of confirmation is required, and how conflicts of interest are handled. GrayPass records the attributed review decision; your review process establishes the supporting evidence and decision criteria.

Outcomes and user messages

Tell the person what happened in operational language: approved, verify again, paused for review, or blocked. Avoid displaying numeric identity certainty. Offer a route to support or your account recovery process when applicable.

Report what actually happened using the outcome API. If your business system did not execute despite an allow, report not_executed. If a reviewer or customer used a separate authorized override process, use the relevant attributed outcome. If the final result is uncertain, reconcile the operation before assigning a terminal outcome.