Authentication
Your API key must be used with any interaction with the Speechmatics API to authenticate to the service. Any interaction without this key will receive a HTTP 401 - Unauthorized response.
It is recommended that you store and provide access to the API key on the principle of least privilege. If you believe that your key has been compromised, please reach out to Support.
Create an API key
To create an API key, first navigate to the Portal and sign in or create an account, if you don't have one already. Then, navigate to Settings > API Keys page to create an API key.
Enter a name for your API key and then store it somewhere safe when you have generated it.
Authenticating
Your API key needs to be included in the header of all requests to the Speechmatics Jobs API. For example:
curl -X GET "https://eu1.asr.api.speechmatics.com/v2/jobs/" \
-H "Authorization: Bearer $API_KEY"
For server-side calls, your API key must be provided in the header of the Websocket connection request. For example:
GET /v2/ HTTP/1.1
Host: eu.rt.speechmatics.com
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer YOUR_API_KEY
User-Agent: Python/3.8 websockets/8.1
For client-side calls, we recommend using temporary keys (JWTs) to authenticate your requests. These can be passed as a query param to the Websocket connection request URL. For example:
wss://eu.rt.speechmatics.com/v2?jwt=$TEMP_KEY
Supported endpoints
All production endpoints are active and highly available. You can use multiple regions to balance requests or provide a failover in the event of disruption to one region.
If you are an enterprise customer and would like to use a different region than the one specified in your contract, please contact your account manager or support.
Speechmatics Batch SaaS supports the following endpoints for production use:
Jobs are created in the region corresponding to the endpoint used. You must use the same endpoint for all requests relating to a specific job.
The EU2 and US2 Batch SaaS endpoints are provided for enterprise customer high availability and failover purposes only. Jobs created in these environments will not be visible in the Portal.
Speechmatics Realtime SaaS supports the following endpoints for production use:
Temporary keys
Speechmatics allows you to generate temporary keys to authenticate your requests instead of your long-lived API key. This can improve end-user experience by reducing latency, and can also reduce development effort and complexity.
If you are an enterprise customer and would like to use temporary keys, reach out to support or speak to your account manager.
For Batch jobs, using temporary keys allows your end-users to upload their audio to Speechmatics directly, without exposing your long-lived API key. This approach can reduce development effort, storage and bandwidth costs.
When you generate a temporary key with a client_ref, that temporary key will only be able to create and retrieve jobs associated with that client_ref.
client_ref should be a string that uniquely identifies an end-user.
Note that temporary keys generated with a client_ref can't access the Usage Batch API endpoint and will receive a HTTP 403 - Forbidden.
If your Batch temporary key will be exposed to end-users, for example in the browser, then you must use the client_ref parameter. This will prevent one user from viewing or deleting the jobs of another user.
The example request below creates a temporary key which can be used to create and retrieve Batch jobs for 60 seconds. These jobs will be associated with the reference 'USER123':
curl -L -X POST "https://mp.speechmatics.com/v1/api_keys?type=batch" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{"ttl": 60, "client_ref": "USER123"}'
The response JSON looks like this:
{
"apikey_id": null,
"key_value": "eyJhbG..."
}
To authorize a request using a temporary key, simply use it in place of the API key in the authorization header.
For example, if you created a temporary key associated with a given client_ref you can retrieve those jobs as follows:
curl -X GET "https://eu1.asr.api.speechmatics.com/v2/jobs/" \
-H "Authorization: Bearer $TEMP_KEY"
For Realtime transcription, temporary keys allow the end-user to start a websocket connection with Speechmatics directly, without exposing your long-lived API key. This will reduce the latency of transcription, as well as development effort.
The example request below will create a temporary key which can be used to start any number of Realtime transcription settings for 60 seconds:
curl -L -X POST "https://mp.speechmatics.com/v1/api_keys?type=rt" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{"ttl": 60 }'
Note that when starting a Realtime transcription session in the browser, you must provide the temporary key as a part of a query parameter. See our documentation on browser based transcription.
Temporary key configuration
Next steps
Get started with the API by trying out the "Hello World" example in the Speechmatics Academy.