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 MyPage, 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.
  • APPKEYs and one-time APPKEYs issued for accounts created before MyPage renewal on 2025/06/30 cannot be deleted. To delete them, you need to cancel your membership and create a new account.
  • APPKEYs issued on MyPage after MyPage renewal on 2025/06/30 can be manually deleted on MyPage. APPKEYs issued using the one-time APPKEY issuance API cannot be deleted.

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 either the service ID (specified in the request body, parameter name is sid) and service password (same, spw), or an APPKEY issued with "APPKEY 発行可能" set on MyPage (specified in the Authorization header). For sid and spw, please set the [Service ID] and [Service Password] listed in "Connection Information" on MyPage.

note

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

caution

Please set sid and spw in the request body using application/x-www-form-urlencoded format. Do not specify them as query parameters (i.e., by appending ? to the end of the URL). The HTTP method for the request must be POST.

The expiration time (request parameter name is epi) can be set arbitrarily. If you specify a numeric value for epi, it will be interpreted in milliseconds. For other configuration methods, please see the reference. If epi is omitted, the default value of 30000 (30 seconds) will be applied. Set this value based on the expected time between issuing the one-time APPKEY and sending the actual AmiVoice API request. You can also specify the IP address allowed to use the APPKEY by setting the ipa parameter.

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

If you want to use an APPKEY instead of sid and spw, it would be as follows:

curl https://acp-api.amivoice.com/issue_service_authorization \
     -d epi=30000 \
     -d ipa=203.0.113.253 \
     -H "Authorization: Bearer {APPKEY capable of issuing APPKEYs}"

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.

APPKEY capable of issuing APPKEYs​

After MyPage renewal on 2025/06/30, it became possible to issue APPKEYs on MyPage that can issue APPKEYs. APPKEYs issued in this way can be used for authentication instead of the service ID (sid) and service password (spw) when making requests to the one-time APPKEY issuance API. To issue an APPKEY as an APPKEY capable of issuing APPKEYs, please check the [発行可能] checkbox in the [APPKEY] section on Issue one-time APPKEY settings screen.

Deleting one-time APPKEYs​

APPKEYs issued on MyPage after MyPage renewal on 2025/06/30 can be manually deleted on MyPage. The procedure is explained below.

  1. Access MyPage dashboard. You can access it directly from this link. Login is required to access MyPage.
  2. From [Connection Information], check the checkbox of the APPKEY you want to delete and click the [Delete] button.
  3. A confirmation screen titled [Delete APPKEY] will be displayed. After confirming that the APPKEY is correct, click the [Delete] button.
  4. An authentication code will be sent to the email address registered to your account. Enter this code in the [Authentication Code Confirmation] screen displayed on MyPage and click the [Send] button.
  5. The APPKEY deletion is complete, and an email notifying you of the APPKEY deletion will be sent to the email address registered to your account.