Integrate: step-up

Who this is for: a team that wants strong, phishing-resistant approval on specific actions without rebuilding their login. If you later want Ydentifi as your second factor everywhere, see Integrate: full.

Step-up or full?#

First, onboard each user — once#

Step-up guards an action for a user Ydentifi already knows. Before the guard can run for someone, you onboard them a single time:

1. Create an opaque identity and store its id next to your user. CreateUser returns a 64-character opaque_id; save it as one more column in the database where you already keep that person.
2. Enroll their device. The user scans an enrolment QR to bind a phone that can approve challenges. See Enroll & link devices.

That opaque_id is the entire link between your world and Ydentifi’s — you keep the real person, Ydentifi only ever sees the token.

Add one column. Ydentifi only ever sees the value in the highlighted column — the name, email, and everything else stay in your database, invisible to it.

Where it goes#

Nothing about how users authenticate to your product changes. You insert a single guard on the server, at the moment a sensitive action is about to run.

The guard, in code#

The whole integration is one function you call before the operation. It issues a challenge over the exact action, waits for the signed result, verifies it, and returns success only on a verified approval:

// install: go get github.com/ydentifi/go

// requireApproval blocks until the user signs off on THIS exact action —
// or denies it. Run it server-side, right before the operation executes.
func requireApproval(ctx context.Context, opaqueID, action string,
    tier ydentifi.AuthStrength) error {

    ch, err := client.IssueAuthChallenge(ctx, ydentifi.IssueAuthChallengeRequest{
        OpaqueID:    opaqueID,
        Context:     []byte(action), // the exact text the user sees and signs
        TTLSeconds:  120,
        MinStrength: tier,           // required — the tier this action demands
    })
    if err != nil { return err }
    // The challenge lands on the enrolled device (or render ch.QREncoded).

    // Blocks until terminal; the deployment verifies and returns the verdict.
    result, err := client.AwaitChallenge(ctx, ch.ChallengeID)
    if err != nil { return err }
    switch result.Status {
    case ydentifi.ChallengeStatusApproved:
        return nil // approved — the caller may proceed
    case ydentifi.ChallengeStatusDenied:
        return ErrDenied
    default:
        return ErrExpired // no answer within the TTL
    }
}

// The call site. Your existing login and session checks are untouched —
// you only add the guard immediately before the sensitive operation.
func handleTransfer(w http.ResponseWriter, r *http.Request) {
    // ... your existing auth / session checks ...

    err := requireApproval(r.Context(), user.OpaqueID,
        "Approve €4,200 transfer to ···· 8842",
        ydentifi.AuthStrengthBiometric)
    if err != nil {
        http.Error(w, "not approved", http.StatusForbidden) // fail closed
        return
    }

    doTransfer() // reached ONLY on a verified APPROVED
}

The same shape works in every SDK — the full create→challenge→await→verify flow and per-language versions are in Your first ceremony and the API reference.

Choosing the tier#

Set the strength to match the stakes of this action — a signed biometric approval for most things, add location for the highest-value ones. You pass it per call, so different actions can demand different tiers. See Factors & levels.

Handle the outcome, fail closed#

There is exactly one path that lets the action run: the frame is APPROVED and its signature verifies. Everything else — denied, expired, a stream error, a bad signature — must block the operation. Treat “not a verified yes” as “no.”