# 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.

{% hint style="info" %}
Secret Management operations are performed as part of the biometric flow, ensuring user authentication before any secret modification.
{% endhint %}

### Key Class

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

{% tabs %}
{% tab title="Android" %}

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

{% endtab %}

{% tab title="iOS" %}

```swift
public struct KeylessSecret {
    public let id: Identifier   // Unique identifier for the secret
    public let value: Value     // The actual secret content
}
```

{% endtab %}
{% endtabs %}

### 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

{% tabs %}
{% tab title="Android" %}

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

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

{% endtab %}

{% tab title="iOS" %}

```swift
let configuration = BiomEnrollConfig(
    savingSecret: KeylessSecret(
        id: "your-secret-id",
        value: "your-secret-value"
    )
)

Keyless.enroll(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            print("Secret saved successfully")
        case .failure(let error):
            print("Error: \(error.message)")
        }
    })
```

{% endtab %}
{% endtabs %}

#### Retrieve a Secret

{% tabs %}
{% tab title="Android" %}

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

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

{% endtab %}

{% tab title="iOS" %}

```swift
let configuration = BiomAuthConfig(
    retrievingSecret: "your-secret-id"
)

Keyless.authenticate(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            if let secret = success.secret {
                print("Secret ID: \(secret.id)")
                print("Secret Value: \(secret.value)")
            }
        case .failure(let error):
            print("Error: \(error.message)")
        }
    })
```

{% endtab %}
{% endtabs %}

#### Delete a Secret

{% tabs %}
{% tab title="Android" %}

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

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

{% endtab %}

{% tab title="iOS" %}

```swift
let configuration = BiomAuthConfig(
    deletingSecret: "your-secret-id"
)

Keyless.authenticate(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success:
            print("Secret deleted successfully")
        case .failure(let error):
            print("Error: \(error.message)")
        }
    })
```

{% endtab %}
{% endtabs %}

#### List All Secret IDs

{% tabs %}
{% tab title="Android" %}

```kotlin
val configuration = BiomAuthConfig(shouldRetrieveSecretIDs = true)

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

{% endtab %}

{% tab title="iOS" %}

```swift
let configuration = BiomAuthConfig(shouldRetrieveSecretIDs: true)

Keyless.authenticate(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            if let secretIDs = success.secretIDs {
                for id in secretIDs {
                    print("Secret ID: \(id)")
                }
            }
        case .failure(let error):
            print("Error: \(error.message)")
        }
    })
```

{% endtab %}
{% endtabs %}

#### Combining Operations

Multiple secret operations can be combined in a single flow:

{% tabs %}
{% tab title="Android" %}

```kotlin
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
    }
}
```

{% endtab %}

{% tab title="iOS" %}

```swift
let configuration = BiomAuthConfig(
    savingSecret: KeylessSecret(
        id: "new-secret-id",
        value: "new-secret-value"
    ),
    retrievingSecret: "existing-secret-id",
    shouldRetrieveSecretIDs: true
)

Keyless.authenticate(
    configuration: configuration,
    onCompletion: { result in
        switch result {
        case .success(let success):
            if let secret = success.secret {
                print("Retrieved secret: \(secret.value)")
            }
            if let secretIDs = success.secretIDs {
                print("All secret IDs: \(secretIDs)")
            }
        case .failure(let error):
            print("Error: \(error.message)")
        }
    })
```

{% endtab %}
{% endtabs %}

### 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

{% hint style="warning" %}
When retrieving or deleting a secret that does not exist, the SDK returns a `20003 - Secret Not Found` error and halts the operation.
{% endhint %}