Voice Biometrics User Group Keys

This describes the web services that manage the access keys in a voice biometric User Group.

A user group access key must be supplied when calling the voice biometric methods on the user API.

Authorisation

The format for the username and password is as follows:

Username	:	cloudID/username (e.g. 1-2-0/bob@example.com)
Password	:	Your API Access Key

For example:

$ curl --user 1-2-0/bob@example.com:WzyPvLMYBUMvFOgXj3S7fg https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user_group/key/list?user_group_name=BobsCompany

Date formats

All dates are of the format YYYY-MM-DD_hh:mm:ss and are in Coordinated Universal Time (UTC).

Response content

All web services in this API return response content of type "application/json".

Note

This is a low level API. For information on higher level APIs see the Web Services Language Wrappers

ListCreateModifyDelete

List

List the access keys in a user group.

Url	:	https://ws.aculabcloud.net/voice_biometrics/v1/user_group/key/list
Methods	:	GET, POST

Parameter	Required/Optional	Default	Description
user_group_name	required		the name of the user group.

Returns on success:

A JSON object containing a list of user group key objects containing the following parameters:

Parameter	Type	Availability	Description
user_group_key	string	always	the user group key.
created	string	always	the creation date and time of the user group key.
enabled	boolean	always	whether the key is currently enabled.
retain_data	boolean	always	whether diagnostic data is retained when using this key (see Modify).

Example:

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user_group/key/list?user_group_name=BobsCompany

If successful you will receive the JSON response:

{
    "user_group_keys": [
        {
            "user_group_key": "ak-CxdoWo/8kzAyBcgny-7qCh9/zfc0",
            "created": "2021-01-15_08:56:24",
            "enabled": true,
            "retain_data": false
        },
        {
            "user_group_key": "ak-OlRlRe8uNPUw0usbnIP2DBiafb0G",
            "created": "2021-01-15_09:21:35",
            "enabled": true,
            "retain_data": false
        },
    ]
}

Create

This creates a user group access key. Each key is guaranteed to be unique within the cloud account and is enabled by default.

Url	:	https://ws.aculabcloud.net/voice_biometrics/v1/user_group/key/create
Methods	:	GET, POST

Parameter	Required/Optional	Default	Description
user_group_name	required		the name of the user group in which to create the access key.

Returns on success:

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
user_group_key	string	always	the newly created user group key.
created	string	always	the creation date and time of the user group key.
enabled	bool	always	the enabled state of the key after creation.
retain_data	boolean	always	whether diagnostic data is retained when using this key (see Modify).

Example:

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user_group/key/create?user_group_name=BobsCompany

If successful you will receive the JSON response:

{
    "user_group_key": "ak-OlRlRe8uNPUw0usbnIP2DBiafb0G",
    "created": "2021-01-15_08:56:24"
    "enabled": true,
    "retain_data": false
}

Or on error the JSON response:

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user group BobsCompany was not found", 
        "link": "https://www.aculab.com/cloud/web-services/voice-biometrics/user_group_keys?target=service_action_tabs&tab-id=create",
        "datetime": "2021-01-15_08:57:32"
    },
    "request": {
        "url": "/voice_biometrics/v1/user_group/key/create",
        "datetime": "2021-01-15_08:57.31"
    }
}

Modify

This modifies a user group access key.

Url	:	https://ws.aculabcloud.net/voice_biometrics/v1/user_group/key/modify
Methods	:	GET, POST

Parameter	Required/Optional	Description
user_group_key	required	the access key to modify.
enabled	required	"true" or "false". Enable or disable the specified access key. If disabled, the key cannot be used to register, update or verify a user.
retain_data	required	"true" or "false". Enable to retain diagnostic audio and transaction data when using this key. During normal operation this should be disabled.

Remarks:

If retain_data is enabled for a key, the voice biometric server will store data associated with all transactions initiated using that key. This diagnostic data is accessible by Aculab only and you will need to contact Support to request it to be analysed. The data is retained for at most one month.

Returns on success:

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
user_group_key	string	always	the newly created user group key.
created	string	always	the creation date and time of the user group key.
enabled	bool	always	the enabled state of the key after the modification.
retain_data	bool	always	the enabled state of the retain_data property after the modification.

Example:

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user_group/key/modify?user_group_key=ak-OlRlRe8uNPUw0usbnIP2DBiafb0Genabled=falseretain_data=false

If successful you will receive the JSON response:

{
    "user_group_key": "ak-OlRlRe8uNPUw0usbnIP2DBiafb0G",
    "created": "2021-01-15_08:56:24"
    "enabled": false,
    "retain_data": false
}

Or on error the JSON response:

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user group BobsCompany was not found", 
        "link": "https://www.aculab.com/cloud/web-services/voice-biometrics/user_group_keys?target=service_action_tabs&tab-id=modify",
        "datetime": "2021-01-15_08:58:22"
    },
    "request": {
        "url": "/voice_biometrics/v1/user_group/key/modify",
        "datetime": "2021-01-15_08:58.21"
    }
}

Delete

This deletes a user group access key.

Url	:	https://ws.aculabcloud.net/voice_biometrics/v1/user_group/key/delete
Methods	:	GET, POST

Parameter	Required/Optional	Default	Description
user_group_key	required		the access key to delete.

Returns on success:

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
deleted	string	always	the deletion date and time of the user group key.

Example:

https://ws-1-2-0.aculabcloud.net/voice_biometrics/v1/user_group/key/delete?user_group_key=ak-OlRlRe8uNPUw0usbnIP2DBiafb0G

If successful you will receive the JSON response:

{
    "deleted": "2021-01-15_08:56:24"
}

Or on error the JSON response:

{
    "error": {
        "code": HTTP 404,
        "text": "Not found: user group BobsCompany was not found", 
        "link": "https://www.aculab.com/cloud/web-services/voice-biometrics/user_group_keys?target=service_action_tabs&tab-id=delete",
        "datetime": "2021-01-15_08:58:47"
    },
    "request": {
        "url": "/voice_biometrics/v1/user_group/key/delete",
        "datetime": "2021-01-15_08:58.46"
    }
}