SDK ログイン

Overview

Before the issuer application calls any D1 SDK service, it must prove that the end user is authenticated.

D1 SDK and D1 backend use this proof to authorize the session.

For example, the issuer application can prompt the end user for biometric authentication.

Example: end user biometric authentication.

Login flow

SDK login flow.

Create the issuer access token with a short expiration time, such as a few minutes. Do not reuse it across multiple login attempts.

Login validity

After login, the end user can access D1 services for the full session.

The default session validity is one hour.

Sensitive D1 services use a shorter validity period. This period is usually a few minutes. If the login is older than that period, the issuer application must authenticate the end user again.

In that case, D1 SDK returns NOT_LOGGED_IN.

Prompt the end user to log in again when you receive this error.

Client binding

Since D1 SDK v4.4.0, client binding strengthens login by binding the issuer access token to the requesting device.

This lets D1 backend verify that later SDK requests come from the authenticated issuer application on the expected device.

With client binding:

• D1 SDK signs each request with device keys.
• D1 backend verifies that the request comes from the registered device.
• Short-lived key pairs reduce the attack surface.

The public key exchange happens during login. This ensures that binding is created only for an authenticated session.

Login flow with client binding.

Steps	Description
01 - 02	Authenticate the end user in the issuer application.
03 - 05	Call getBindingHash before login. The API returns an encoded, hashed client binding payload as a String. For iOS integrations, call D1Task.bindingHash() during application startup when possible. Run it in the background. The first call performs the initial binding setup and can take longer. This extra latency usually happens only when iOS binding material is created or refreshed, typically about once every two months. Send the client binding payload to the issuer backend, do not modify, transform, or re-encode it.
06	Build the issuer access token. The issuer backend creates the issuer access token and adds the client binding payload as the cbp claim. See Access token format. Create the issuer access token with a short expiration time, such as a few minutes. Do not reuse it across multiple login attempts.
07 - 09	Call login with the updated issuer access token. After login, D1 backend uses the cbp claim for device-binding checks on later SDK requests.
10 - 18	The issuer application calls any operation and D1 SDK handles the security behind the scene with the D1 backend.

SDK implementation

Use the following examples.

For iOS devices, the end user must set a device passcode before bindingHash() or login() is called. Otherwise, D1 SDK returns an error.

Android Java

public void login(@NonNull D1Task d1Task) throws D1Exception {
    String cbp = d1Task.getBindingHash(); // Must be called if client binding is enabled.
    
    // TODO: replace with the issuer access token returned by your issuer backend. 
    // The token must include cbp as a claim, if client binding is enabled.
    byte[] issuerToken = "<<issuer access token>>".getBytes(); 
    D1Task.Callback<Void> callback = new D1Task.Callback<Void>() {
        @Override
        public void onSuccess(Void ignore) {
            // Proceed with subsequent flows
        }

        @Override
        public void onError(D1Exception exception) {
            // Refer to D1 SDK Integration – Error Management section
        }
    };
    d1Task.login(issuerToken, callback);
}

Android Kotlin

iOS