API key permissions

Overview

Every API key in a project has a list of permissions. Each permission lets the key use one part of the Soniox API, such as real-time transcription or file management. A call to anything else is refused with permission_denied.

Give each key only the access it needs. For example, if your server uses a key only to create temporary API keys for a browser, that key does not need access to your files or your usage data. If it leaks, the damage is limited.

Setting permissions

1. In the Soniox Console, open your project and go to API keys.
2. Select Create API key and give the key a name.
3. Turn on Full access, or choose a level for each permission the key needs.
4. Create the key and copy it. The full key is shown only once.

Only organization admins can create and edit keys.

Permissions

• Speech-to-text, real-time: the Speech-to-Text WebSocket API.
• Speech-to-text, async: transcriptions. This permission is enough to transcribe a file that is already uploaded. Uploading the file needs Files.
• Files: uploading and managing files.
• Text-to-speech, real-time: the Text-to-Speech WebSocket API and the REST endpoint, including speech generated with a cloned voice.
• Cloned voices: managing cloned voices.
• Usage and limits: usage logs, usage summary, concurrency limits and concurrent streams history.
• Model listing: STT models, TTS models and shared voices.
• Temporary API keys: creating temporary API keys. This needs a second permission, see below.

Async transcription, files and cloned voices have two levels. Read allows listing and fetching. Write allows everything Read does, plus creating and deleting. The other permissions are either on or off.

Temporary API keys

Creating a temporary API key needs two permissions: Temporary API keys, and the permission for the service in usage_type.

Temporary API keys have no permissions of their own. A temporary key can do what its usage_type allows.

Editing a key

You can change the name and permissions of a key at any time. The key itself stays the same.

Errors

A call that the key has no permission for is refused with HTTP status 403. This means the key is valid but does not have the permission. An invalid or deleted key gets 401 unauthenticated instead.

{
  "status_code": 403,
  "error_type": "permission_denied",
  "message": "The API key does not have permission for this product. Edit the key's permissions at https://console.soniox.com",
  "validation_errors": [],
  "request_id": "b4c1f4d5-8d8e-4a1c-9a8c-2a0e6f7c1d3e",
  "more_info": "https://soniox.com/docs/api-reference/errors#permission-denied"
}