API reference

// The RP is identified by its mTLS client cert, so the request is empty.
res, err := client.CreateUser(ctx, &identity.CreateUserRequest{})
if err != nil { /* handle error */ }
opaqueID := res.OpaqueId  // 64-char hex — store it against your user

creds := credentials.NewTLS(&tls.Config{
    Certificates: []tls.Certificate{rpCert}, // your client cert
    RootCAs:      trustPool,                 // your deployment CA
})
conn, err := grpc.Dial("ydentifi.acme.internal:443", grpc.WithTransportCredentials(creds))
if err != nil { /* handle */ }
defer conn.Close()
client := identity.NewIdentityServiceClient(conn)
res, err := client.CreateUser(ctx, &identity.CreateUserRequest{})
if err != nil { /* handle */ }
fmt.Println(res.GetOpaqueId())

res = client.CreateUser(identity_pb2.CreateUserRequest())
opaque_id = res.opaque_id

const res = await client.createUser({});
const opaqueId = res.opaqueId;

stream, err := client.BulkCreateUsers(ctx, &identity.BulkCreateUsersRequest{
    Count:          1000,
    IdempotencyKey: "batch-2026-07-24-a", // re-send to resume a partial run
})
if err != nil { /* handle */ }
for {
    frame, err := stream.Recv()
    if err == io.EOF { break }
    if err != nil { /* handle */ }
    switch f := frame.Frame.(type) {
    case *identity.BulkCreateUsersFrame_Chunk:
        store(f.Chunk.OpaqueIds)              // persist as they arrive
    case *identity.BulkCreateUsersFrame_Summary:
        log.Printf("created %d of %d (capped %d)",
            f.Summary.Created, f.Summary.Requested, f.Summary.Capped)
    }
}

res, err := client.GetUser(ctx, &identity.GetUserRequest{OpaqueId: opaqueID})
if err != nil { /* handle */ }
fmt.Println(res.Status, res.LastAuthenticatedAt)

stream, err := client.ExportUsers(ctx, &identity.ExportUsersRequest{})
if err != nil { /* handle */ }
for {
    batch, err := stream.Recv()
    if err == io.EOF { break }
    if err != nil { /* handle */ }
    for _, u := range batch.Users { archive(u) }   // server dictates batch size
}

_, err := client.UpdateUserStatus(ctx, &identity.UpdateUserStatusRequest{
    OpaqueId: opaqueID,
    Status:   identity.UserStatus_USER_STATUS_LOCKED,
})
if err != nil { /* handle */ }

_, err := client.DeleteUser(ctx, &identity.DeleteUserRequest{OpaqueId: opaqueID})
if err != nil { /* handle */ }

_, err := client.UnlockUserRequestLimits(ctx,
    &identity.UnlockUserRequestLimitsRequest{OpaqueId: opaqueID})
if err != nil { /* handle */ }

res, err := client.ListDevicesForUser(ctx,
    &identity.ListDevicesForUserRequest{OpaqueId: opaqueID})
if err != nil { /* handle */ }
for _, d := range res.Devices {
    fmt.Println(d.DeviceId, d.Platform, d.Status) // INACTIVE rows included
}

_, err := client.RevokeDevice(ctx, &identity.RevokeDeviceRequest{
    OpaqueId: opaqueID,
    DeviceId: deviceID, // from ListDevicesForUser
})
if err != nil { /* handle */ }

res, err := client.BanDevice(ctx, &identity.BanDeviceRequest{
    OpaqueId: opaqueID,
    DeviceId: deviceID,
    Reason:   "lost device report", // optional, persisted for audit
})
if err != nil { /* handle */ }
log.Printf("banned; %d active enrollments deactivated", res.CascadedDeviceCount)

_, err := client.UnbanDevice(ctx, &identity.UnbanDeviceRequest{
    OpaqueId: opaqueID,
    DeviceId: deviceID,
})
if err != nil { /* handle */ }
// the user must re-enroll — old enrollments are NOT restored

iss, err := client.IssueAuthChallenge(ctx, &identity.IssueAuthChallengeRequest{
    OpaqueId:    opaqueID,
    TtlSeconds:  120, // [30,300]; 0 = 60s default
    Context:     []byte("Approve a $4,200 transfer to ...8842"),
    MinStrength: identity.AuthStrength_AUTH_STRENGTH_BIOMETRIC, // level 2 — biometric, no passcode fallback
})
if err != nil { /* handle */ }
render(iss.QrEncoded) // draw the Universal-Link QR, or push it to the device

// Same call, no SDK sugar (see CreateUser for the mTLS dial preamble).
iss, err := client.IssueAuthChallenge(ctx, &identity.IssueAuthChallengeRequest{
    OpaqueId: opaqueID, TtlSeconds: 120,
    Context:     []byte("Approve login from Sofia"),
    MinStrength: identity.AuthStrength_AUTH_STRENGTH_BIOMETRIC,
})
if err != nil { /* handle */ }
fmt.Println(iss.GetChallengeId(), iss.GetQrEncoded())

iss = client.IssueAuthChallenge(identity_pb2.IssueAuthChallengeRequest(
    opaque_id=opaque_id, ttl_seconds=120,
    context=b"Approve a $4,200 transfer",
    min_strength=identity_pb2.AUTH_STRENGTH_BIOMETRIC))
render(iss.qr_encoded)

const iss = await client.issueAuthChallenge({
  opaqueId, ttlSeconds: 120,
  context: new TextEncoder().encode("Approve a transfer"),
  minStrength: AuthStrength.BIOMETRIC,
});
render(iss.qrEncoded);

stream, err := client.AwaitChallenge(ctx,
    &identity.AwaitChallengeRequest{ChallengeId: challengeID})
if err != nil { /* handle */ }
for {
    frame, err := stream.Recv()
    if err == io.EOF { break } // stream closes on a terminal state
    if err != nil { /* handle */ }
    switch frame.Status {
    case identity.AuthChallengeStatus_AUTH_CHALLENGE_STATUS_APPROVED:
        grant(frame.AuthStrength) // the tier reached, which may beat what you asked for
    case identity.AuthChallengeStatus_AUTH_CHALLENGE_STATUS_DENIED:
        log.Printf("denied: %v", frame.DeclineReason)
    }
}

stream, err := client.AwaitChallenge(ctx,
    &identity.AwaitChallengeRequest{ChallengeId: challengeID})
if err != nil { /* handle */ }
for {
    frame, err := stream.Recv()
    if err == io.EOF { break }
    if err != nil { /* handle */ }
    log.Printf("status=%s strength=%s", frame.GetStatus(), frame.GetAuthStrength())
}

for frame in client.AwaitChallenge(
        identity_pb2.AwaitChallengeRequest(challenge_id=challenge_id)):
    if frame.status == identity_pb2.AUTH_CHALLENGE_STATUS_APPROVED:
        grant(strength=frame.auth_strength); break
    if frame.status == identity_pb2.AUTH_CHALLENGE_STATUS_DENIED:
        raise Denied(frame.decline_reason)

for await (const frame of client.awaitChallenge({ challengeId })) {
  if (frame.status === AuthChallengeStatus.APPROVED) { grant(frame.authStrength); break; }
  if (frame.status === AuthChallengeStatus.DENIED)  throw new Denied(frame.declineReason);
}

res, err := client.ListActiveChallenges(ctx,
    &identity.ListActiveChallengesRequest{OpaqueId: opaqueID})
if err != nil { /* handle */ }
for _, c := range res.Challenges {
    fmt.Println(c.ChallengeId, c.Status, c.ExpiresAt)
}

inv, err := client.IssueEnrollmentInvite(ctx, &identity.IssueEnrollmentInviteRequest{
    OpaqueId:   opaqueID,
    TtlSeconds: 300, // [60,600]; 0 = 300 default
    Context:    []byte("Add a device for Acme Bank"),
})
if err != nil { /* handle */ }
render(inv.QrPayload) // show as a QR for the user's Ydentifi app to scan

inv, err := client.IssueRecoveryInvite(ctx, &identity.IssueRecoveryInviteRequest{
    OpaqueId:   opaqueID,
    TtlSeconds: 300,
    Context:    []byte("Recover your account on a new device"),
})
if err != nil { /* handle */ }
// Issuing the invite ALREADY revoked every active device for this user.
log.Printf("%d active devices revoked", inv.RevokedDeviceCount)
render(inv.QrPayload)

inv, err := client.IssueUserTotpEnrollment(ctx, &identity.IssueUserTotpEnrollmentRequest{
    OpaqueId:      opaqueID,
    ReuseExisting: false, // false mints a fresh secret; true re-issues the current one
})
if err != nil { /* handle */ }
// inv.TotpUrl is the otpauth:// URL; inv.QrCodePngBase64 is a ready 512x512 QR.
// inv.SecretBase32 is sensitive — never log or persist it in plaintext.
render(inv.QrCodePngBase64)

res, err := client.VerifyUserTotp(ctx, &identity.VerifyUserTotpRequest{
    OpaqueId: opaqueID,
    TotpCode: "492817",
})
if err != nil {
    // Typed reason lives in the error details — read it, don't parse strings.
    if d := identity.ErrorDetailFrom(err); d != nil {
        switch d.Reason {
        case identity.ErrorReason_RATE_LIMIT_EXCEEDED: // back off
        case identity.ErrorReason_TOTP_NOT_ENROLLED: // prompt enrollment
        }
    }
    return err
}
if !res.Valid { /* wrong code */ }

try:
    res = client.VerifyUserTotp(identity_pb2.VerifyUserTotpRequest(
        opaque_id=opaque_id, totp_code="492817"))
except grpc.RpcError as e:
    detail = error_detail_from(e)          # reads ErrorDetail from status
    if detail.reason == identity_pb2.RATE_LIMIT_EXCEEDED:
        backoff()
    raise
ok = res.valid

const res = await client.verifyUserTotp({ opaqueId, totpCode: "492817" })
  .catch((e) => {
    const d = errorDetailFrom(e);
    if (d?.reason === ErrorReason.RATE_LIMIT_EXCEEDED) backoff();
    throw e;
  });
const ok = res.valid;

exp, err := client.GetCertificateExpiry(ctx, &identity.GetCertificateExpiryRequest{})
if err != nil { /* handle */ }
fmt.Println(exp.ExpiresAt, exp.Fingerprint, exp.CertTtlDays)
// Drive your own "cert expires in N days" warning off exp.ExpiresAt.

res, err := client.SetCertificateTTL(ctx, &identity.SetCertificateTTLRequest{
    CertTtlDays: 730, // preference applied to your NEXT rotation
})
if err != nil { /* handle */ }
fmt.Println("stored ttl days:", res.CertTtlDays) // echoed back

res, err := client.RotateCertificate(ctx, &identity.RotateCertificateRequest{
    CsrPem: csrPEM, // you generate a fresh keypair + CSR
})
if err != nil { /* handle */ }
install(res.CertPem)
// The OLD cert stays valid for res.GracePeriodSeconds — hot-reload
// your listeners inside that window to avoid dropping connections.