Skip to main content

Credential management

Apart from registering and authenticating with a credential, your users require the ability to self-manage their own credentials. To exemplify how the Hanko API enables credential management, assume a simple user profile section in your relying party frontend as shown in the following mockup:

Credential management interface mockup
Figure 1: Credential management interface mockup

In this profile sections users can:

  1. view a list of their registered credentials along with metadata for individual credentials (e.g. a custom name, authenticator type, date of registration etc.) - see Retrieve credentials
  2. deregister a credential (for example in case of device loss) - see Deregister credentials
  3. rename registered credentials - see Rename credentials

Retrieve credentials#

The API allows you to retrieve both a list of credentials (optionally paginated and filtered by a user ID) and single credentials by credential ID.

Get a list of registered credentials#

To retrieve a list of registered credentials, issue a GET request to the /v1/webauthn/credentials endpoint (see also the API reference). Credentials can be filtered using a user_id as a query parameter.

Get registered credentials for user - /v1/webauthn/credentials
curl -X GET 'API_BASE_URL/v1/webauthn/credentials?user_id=USER_ID' \
-H 'Authorization: secret API_SECRET'

The API returns a list of credential objects that contain metadata about the registered credential (see the API reference for a detailed description of its properties).

Example JSON response: credential list
[
{
"id": "dYbKuEGZpnamd5DU8m3b8l4oh6OBMqnesdvHS9mlsNA",
"user": {
"id": "e3be22a7-13cf-4235-a09c-380dfd44ac04"
},
"createdAt": "2021-04-29T08:45:11.858984Z",
"lastUsed": "2021-04-29T08:45:11.85898Z",
"name": "My Yubikey",
"userVerification": true,
"isResidentKey": false,
"authenticator": {
"aaguid": "f244b67e-5364-4fd5-9f90-c396227317db"
}
},
{
"id": "U0-8xnjB7qKNU47llamQqyE6N-OheMID-XeyLT2LaVU",
"user": {
"id": "e3be22a7-13cf-4235-a09c-380dfd44ac04"
},
"createdAt": "2021-04-29T08:45:12.033146Z",
"lastUsed": "2021-04-29T08:45:12.033144Z",
"name": "My MacBook",
"userVerification": true,
"isResidentKey": false,
"authenticator": {
"aaguid": "a7d6d93a-8a0d-11e8-9a94-a6cf71072f73"
}
}
]

Get a single credential#

To retrieve a single credential, issue a GET request to the /v1/webauthn/credentials/:credential_id endpoint (see also the API reference).

Get registered credential - /v1/webauthn/credentials/:credential_id
curl -X GET 'API_BASE_URL/v1/webauthn/credentials/CREDENTIAL_ID' \
-H 'Authorization: secret API_SECRET'

The API returns a single credential object that contains metadata about the registered credential (see the API reference for a detailed description of its properties).

Example JSON response: credential
{
"id": "dYbKuEGZpnamd5DU8m3b8l4oh6OBMqnesdvHS9mlsNA",
"user": {
"id": "e3be22a7-13cf-4235-a09c-380dfd44ac04"
},
"createdAt": "2021-04-29T08:45:11.858984Z",
"lastUsed": "2021-04-29T08:45:11.85898Z",
"name": "My Yubikey",
"userVerification": true,
"isResidentKey": false,
"authenticator": {
"aaguid": "f244b67e-5364-4fd5-9f90-c396227317db"
}
}

Deregister credentials#

There are some scenarios in which the deregistration of a credential with a service might be desired, for example in the case of account removal or authenticator device loss.

To deregister an existing credentials, issue a DELETE request to the /v1/webauthn/credentials/:credential_id endpoint (see also the API reference).

Deregister credential by credential ID - /v1/webauthn/credentials/:credential_id
curl -X DELETE 'API_BASE_URL/v1/webauthn/credentials/CREDENTIAL_ID \
-H 'Authorization: secret API_SECRET'

On successful deregistration, the API returns a response with a simple HTTP 204 - No Content status.

note

Credential deregistration removes only public credential material on the server side. This means that private credential material will remain on an authenticator device unless a user explicitly deletes it from the authenticator. How credential material can be removed depends on the model of the authenticator: some manufacturers like Yubico offer dedicated software that provides a device settings UI, allowing for resetting the authenticator device. Google Chrome's security settings also allow you interact with security keys (e.g. via entering chrome://settings/securityKeys in the URL bar) and resetting the data on it.

Rename credentials#

Credentials have a name property that allows for easily distinguishing registered credentials (e.g. "My MacBook" or "My Yubikey"). On registration this name has a default initial value but credentials can be renamed by issuing a PUT request to the /v1/webauthn/credentials/:credential_id endpoint (see also the API reference). Provide the desired new credential name in the request body.

Update registered credential - /v1/webauthn/credentials/:credential_id
curl -X PUT 'API_BASE_URL/v1/webauthn/credentials/CREDENTIAL_ID' \
-H 'Content-Type: application/json'
-H 'Authorization: secret API_SECRET'
-d '{ "name": "My Yubikey" }'

On successful update the API returns the updated credential.

Try the example application#

Are you looking for a more immersive learning experience? See how it all works by trying out our example application.