Manage Credentials

Manage the set of verifiable credentials received and owned by the agent

After accepting and storing a credential from a connection, credentials will be available for management under the agent's CredentialsModule. Credentials available in this module are ready to be used in Decentralized Identity interactions, such as when presenting credential proofs. The CredentialsModule provides users with an easy way to fetch, edit and delete credentials in the agent's wallet.

The functionality of the CredentialsModule is accessed via the agent's fields: agent.credentials. The functionality provided is described below.

Get a Credential by ID

Received verifiable credentials are represented by Credential objects. To retrieve the current state of a specific Credential in the agent's wallet, the getById API can be used. If a credential cannot be found by the given identifier, then null is returned:

Swift

let id: String // ID of the credential to get ([Credential.credentialId])

do {
    let credential = try await agent.credentials.getById(credentialId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the credential to get ([Credential.credentialId])

launch {
    try {
        val credential = agent.credentials.getById(id)
    } catch (e: CredentialsModule.GetException) {
        // Handle exception
    }
}

Delete a Credential by ID

Similarly, a Credential in the wallet can be easily deleted via the deleteById API:

Swift

let id: String // ID of the credential to delete ([Credential.credentialId])

do {
    try await agent.credentials.deleteById(credentialId: id)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the credential to delete ([Credential.credentialId])

launch {
    try {
        agent.credentials.deleteById(id)
    } catch (e: CredentialsModule.DeleteException) {
        // Handle exception
    }
}

Updating the Metadata of a Credential

Credentials contain metadata that can be controlled by SDK consumers, allowing custom information to be attached to each Credential, and allowing custom listing functionality to be leveraged.

Each Credential contains a list of RecordTag (Credential.tags) attached to it, where a RecordTag is simply a name-value pair stored with the record. By default, some tags are attached to a new Credential, this includes:

• tag-name: ~created_timestamp, tag-value: The UNIX epoch seconds which this credential was stored

The tags on a Credential can be replaced or updated by using the updateCredential API, and providing a new set to update. This will replace whatever the current set of tags is:

Swift

let id: String // ID of the credential to update ([Credential.credentialId])

// add a 'category' of 'work' to this credential, and a 'priority' of '1'
let update = CredentialUpdate(tags: [
    RecordTag(name: "category", value: "work"),
    RecordTag(name: "~priority", value: "1")
])

do {
    try await agent.credentials.updateCredential(credentialId: id, credentialUpdate: update)
} catch {
    // handle error
}

Kotlin

val id: String // ID of the credential to update ([Credential.credentialId])

// add a 'category' of 'work' to this credential, and a 'priority' of '1'
val update = CredentialUpdate(
    tags = listOf(
         RecordTag("category", "work"),
         RecordTag("~priority", "1")   
    )
)

launch {
    try {
        agent.credentials.updateCredential(id, update)
    } catch (e: CredentialsModule.UpdateException) {
        // Handle exception
    }
}

Like most data in the wallet, RecordTag will be stored encrypted. Unless, the tag name is prefixed with ~, then the tag value will be stored unencrypted. Storing a tag value as unencrypted will allow some additional listing queries to be performed (see below).

Listing Pending Credentials

To list all credentials in the agent's wallet, the listAll API can be used:

Swift

do {
    let creds = try await agent.credentials.listAll(options: nil)
} catch {
    // handle error
}

Kotlin

launch {
    try {
        val creds: List<Credential> = agent.credentials.listAll(null)
    } catch (e: CredentialsModule.ListException) {
        // Handle exception
    }
}

Filtered Listing

More complicated Credential list queries can also be achieved by utilizing the ListCredentialsFilters.

To filter by tags applied to the Credential (i.e. applied via the update API), the tagFilter field of ListCredentialsFilters should be used. This field takes a String in compliance with a Wallet Query Langauge (WQL) Query.

Continuing from the example in the Update section:

Swift

// WQL Query, filter for 'category' == 'work'
let wqlQuery = "{ \"category\": \"work\" }"
let filters = ListCredentialsFilters(tagFilter: wqlQuery)
let options = ListCredentialsOptions(filters: filters)
do {
    let workCredentials = try await agent.credentials.listAll(options: options)
} catch {
    // handle error
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
let wqlQuery = "{ \"~priority\": { \"$lt\": \"2\" } }"
let filters = ListCredentialsFilters(tagFilter: wqlQuery)
let options = ListCredentialsOptions(filters: filters)

do {
    let highPriorityCredentials = try await agent.credentials.listAll(options: options)
} catch {
    // Handle error
}

Kotlin

// WQL Query, filter for 'category' == 'work'
val wqlQuery = """{ "category": "work" }"""
val filters = ListCredentialsFilters(tagFilter = wqlQuery)
val options = ListCredentialsOptions(filters)

launch {
    try {
        val workCredentials = agent.credentials.listAll(options)
    } catch (e: CredentialsModule.ListException) {
        // Handle exception
    }
}

// WQL Query, filter for priority < 2 (e.g. 'high' priority items)
val wqlQuery = """{ "~priority": { "${"$"}lt": "2" } }"""
val filters = ListCredentialsFilters(tagFilter = wqlQuery)
val options = ListCredentialsOptions(filters)

launch {
    try {
        val highPriorityCredentials = agent.credentials.listAll(options)
    } catch (e: CredentialsModule.ListException) {
        // Handle exception
    }
}