Skip to main content

How to Use the API Key Issuance API

Implementation to Use the API Key Issuance API​

When using an API key issued through the API Key Issuance API, the following implementation method can be considered:

  1. Authenticate the application user by some method
  2. After successful authentication, use the API Key Issuance API on the server side to issue an API key with an expiration date and send it to the application
  3. The application uses the issued API key to access the AmiVoice API

Below, we explain how to use the API Key Issuance API. For API details, please see the API Key Issuance.

Endpoint​

POST https://acp-api.amivoice.com/issue_service_authorization

Request​

To use the API Key Issuance API, you need either a Service ID (specified in the request body with parameter name sid) and Service Password (same, spw), or an API key issued with API key issuance functionality enabled on MyPage (specified in the Authorization header). For sid and spw, set the [Service ID] and [Service Password] listed in the "Connection Information" on MyPage.

The API Key Issuance API allows you to set an expiration time and IP address restrictions. The validity period (request 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 API Key Issuance. If epi is omitted, the default value of 30000 (30 seconds) is set. Set this considering the time from issuing the API key to actually sending the AmiVoice API request. To apply IP address restrictions, you can specify the source IP address that can use the API key in ipa.

API key issuance feature cannot be granted.

note

The Service Password (spw) is different from the password used to log in to MyPage.

caution

Set sid and spw in the request body in application/x-www-form-urlencoded format. Do not specify them as query parameters (appended to the URL with ?). The HTTP method for the request is POST.

Request Examples​

Here are examples of issuing an API key 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 using an API key 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 {API_KEY_WITH_API_KEY_ISSUANCE_FEATURE}"

Example 2

The expiration can also be specified as a string using time units (2 hours in this case). If you want to allow a range of IP addresses, you can specify it using CIDR notation.

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

Example 3

The expiration can also be specified as a date and time. Multiple IP addresses or ranges can be specified by separating them with commas or spaces.

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

Response​

If the request is successful, the response will be in plain text, returning the issued API key. This can be directly set as the authorization key in the request parameters.

How to Handle Errors​

Cases Where Authentication Fails with the Issued API Key​

Authentication Error Due to Delay (Expiration)​

If the timing of receiving the authentication request with the authorization key is after the expiration date and time set for the API key, the voice recognition service will return an error like the following. In this case, please obtain a new API key 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 API key, and -21s is the delay time from the expiration.

Even if no error occurs in the s command response packet, if time passes until the first p packet is sent and the expiration date and time is exceeded, 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 or Password​

Even if the Service ID and Service Password specified in the API Key Issuance API are incorrect, an API key will be issued. When making an AmiVoice API request using an invalid API key created with incorrect Service ID or 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 validate service authorization

In this case, please check if the Service ID (sid) and Service Password (spw) specified when requesting the API key issuance are correct values.