Skip to main content

One-time APPKEY

Secure Handling of APPKEY​

The APPKEY is a "service authentication key string" used by applications to access the AmiVoice API, and if leaked, it could be misused. Embedding the APPKEY in an application risks extraction by malicious third parties. Generally, do not send your own APPKEY to machines of application users. Instead, use a one-time APPKEY with an expiration date to minimize the impact of potential leaks.

note
  • A one-time APPKEY is a "service authentication key string" with similar functionality to the APPKEY listed in My Page, but differs in that it has an "expiration date and time" based on the "issue date and valid time". It can also restrict the source IP address.
  • There is no limit to the number of one-time APPKEYs that can be issued.
caution
  • Especially for web applications, avoid writing the APPKEY in HTML or JavaScript, as it would be visible to website users.
  • If embedding the APPKEY in an application is unavoidable, obfuscate or encrypt the APPKEY. This makes it more difficult to extract the APPKEY from the application.
  • The APPKEY cannot be changed. To change it, you need to cancel your membership and create a new account.
  • One-time APPKEYs issued without an expiration date cannot be changed or invalidated, just like the APPKEY on My Page, so please carefully consider before using them.

Using One-time APPKEY​

When using a one-time APPKEY, the following implementation method can be considered:

  1. Authenticate the application user by some method
  2. After successful authentication, issue a one-time APPKEY with an expiration date on the server side and send it to the application
  3. The application uses the one-time APPKEY to access the AmiVoice API

Below, we explain how to use the one-time APPKEY issuance API.

Request​

To use the one-time APPKEY issuance API, you need to set the service ID (query parameter name is sid) and service password (spw). Set the [Service ID] and [Service Password] listed in the "Common Connection Information" of "Connection Information" on My Page.

note

The service password is different from the password used to log in to My Page.

The valid time (query parameter name is epi) can be set arbitrarily. If you set a numerical value for epi, it will be in milliseconds. For other setting methods, please see the reference. If epi is omitted, the default value of 30000 (30 seconds) is set. Set it considering the time from issuing the one-time APPKEY to actually sending the AmiVoice API request. You can specify the IP address that can use the APPKEY in ipa.

Let's try issuing a one-time APPKEY using the curl command.

Example 1

Restrict access to only IP address 203.0.113.253 and set the expiration to 30 seconds after issuance.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={ServiceID} \
     -d spw={ServicePassword} \
     -d epi=30000 \
     -d ipa=203.0.113.253

Example 2

If you want to allow a range of IP addresses, you can specify it using CIDR.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={ServiceID} \
     -d spw={ServicePassword} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24

Example 3

You can also specify multiple IP addresses or ranges by separating them with commas.

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d sid={ServiceID} \
     -d spw={ServicePassword} \
     -d epi=30000 \
     -d ipa=203.0.113.0/24,198.51.100.0/24

Response​

The response is in plain text and returns the one-time APPKEY. You can set it directly as the authorization key in the request parameters.

How to Handle Errors​

Cases Where Connection Authentication with One-time APPKEY Fails​

Authentication Error Due to Delay (Expiration)​

If the timing of receiving the authentication request with the authorization key is past the expiration date and time set for the one-time APPKEY, the speech recognition service will return an error like the following, so please obtain a new one-time APPKEY and try again.

HTTP Interface Error Response

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket Interface Error Response

s service authorization has expired: 20XX/XX/XX XX:XX:XX.000 +0000 (-21s)

The 20XX/XX/XX XX:XX:XX.000 included in the s response is the expiration date and time of the one-time APPKEY, and -21s is the delay time from the expiration.

Even if no error occurs in the s command response packet, if time passes and the expiration date and time is exceeded before sending the first p packet, the following error response will be returned immediately after sending the first p packet.

p can't feed audio data to recognizer server

After successfully starting to send p packets, it will not expire in the middle.

Authentication Error Due to Invalid ID​

Even if the service ID and service password specified for the one-time APPKEY issuance API are incorrect, a one-time APPKEY will be issued. When making an AmiVoice API request using an invalid one-time APPKEY created with incorrect service ID and password, it will return an authentication error like the following.

HTTP Interface Error Response

{
    "code":"-"
    "message":"received illegal service authorization"
}

WebSocket Interface Error Response

s can't verify service authorization

In this case, please check if the service ID (sid) and service password (spw) specified when requesting the one-time APPKEY issuance are correct values.

For details on the one-time APPKEY issuance API, please see One-time APPKEY Issuance API in the reference.

Using One-time APPKEY with Asynchronous HTTP Interface​

When using a one-time APPKEY with the asynchronous HTTP interface, set the expiration time sufficiently long. Typically, it takes several minutes before speech recognition starts. Also, in rare cases during congestion, it may temporarily stop and restart, and authentication may be required even during recognition.