6️⃣ Secret management

The Secret Management feature allows you to securely store, retrieve, update, and delete secrets during enrollment or authentication flows. Secrets can be anything you can save as an ASCII string (such as an API key provided via backend or the seed of an OTP protocol) and are stored in the Keyless Secrets Vault, associated with the user's Keyless ID.

Secret Management operations are performed as part of the biometric flow, ensuring user authentication before any secret modification.

Key Class

The KeylessSecret class represents a secret stored in the Keyless Secrets Vault:

Android

public class KeylessSecret(
    public val id: Identifier,  // Unique identifier for the secret
    public val value: Value     // The actual secret content
)

iOS

Configuration Parameters

Secret Management parameters are available in both BiomEnrollConfig and BiomAuthConfig and he same APIs work for both enrollment and authentication flows. You can adapt any sample shown below by replacing Keyless.enroll with Keyless.authenticate (or vice versa) and using the corresponding configuration class.

Parameter	Type	Description
savingSecret	KeylessSecret?	Secret to create/update
deletingSecret	KeylessSecret.Identifier?	Secret ID to delete
retrievingSecret	KeylessSecret.Identifier?	Secret ID to retrieve
shouldRetrieveSecretIDs	Boolean	Whether to retrieve all secret IDs (default: false)

Operations

Create/Update a Secret

Android

val configuration = BiomEnrollConfig(
    savingSecret = KeylessSecret.of(
        id = "your-secret-id",
        value = "your-secret-value"
    )
)

Keyless.enroll(configuration = configuration) { keylessResult ->
    // Handle the result
}

iOS

Retrieve a Secret

Android

val configuration = BiomAuthConfig(
    retrievingSecret = KeylessSecret.Identifier("your-secret-id")
)

Keyless.authenticate(configuration = configuration) { keylessResult ->
    if (keylessResult is KeylessResult.Success) {
        val secret = keylessResult.value.secret
    }
}

iOS

Delete a Secret

Android

val configuration = BiomAuthConfig(
    deletingSecret = KeylessSecret.Identifier("your-secret-id")
)

Keyless.authenticate(configuration = configuration) { keylessResult ->
    // Handle the result
}

iOS

List All Secret IDs

Android

val configuration = BiomAuthConfig(shouldRetrieveSecretIDs = true)

Keyless.authenticate(configuration = configuration) { keylessResult ->
    if (keylessResult is KeylessResult.Success) {
        val secretIDs = keylessResult.value.secretIDs
    }
}

iOS

Combining Operations

Multiple secret operations can be combined in a single flow:

Android

val configuration = BiomAuthConfig(
    savingSecret = KeylessSecret.of(
        id = "new-secret-id",
        value = "new-secret-value"
    ),
    retrievingSecret = KeylessSecret.Identifier("existing-secret-id"),
    shouldRetrieveSecretIDs = true
)

Keyless.authenticate(configuration = configuration) { keylessResult ->
    if (keylessResult is KeylessResult.Success) {
        val retrievedSecret = keylessResult.value.secret
        val allSecretIDs = keylessResult.value.secretIDs
    }
}

iOS

Result Objects

When secret operations are included in a flow, the retrieved secrets and secret IDs are available in the respective result objects. Please refer to Enrollment success result and Authentication success result for more details.

Error Handling

When retrieving or deleting a secret that does not exist, the SDK returns a 20003 - Secret Not Found error and halts the operation.