Organization API

Overview

The Organization API gives access to your organization as a whole, instead of to one project. Use it to monitor spend and limits across all projects, or to create and delete project API keys from your own tooling.

With the Organization API you can read and manage:

• Organization profile and projects: the organization and its projects.
• Balance and spend: the prepaid balance and billing setup.
• Usage and limits across projects: monthly usage, the daily usage summary per project and model, and limits.
• Project API keys: listing, creating and deleting the API keys of any project.

The endpoints are under https://api.soniox.com/v1/organization and need an organization API key.

Organization API keys

An organization API key is a dedicated key for the Organization API. Organization API keys start with snx_org_, so you can tell them apart from project API keys. The two kinds are not interchangeable. An organization API key cannot call Speech-to-Text, Text-to-Speech or other project endpoints, and a project API key cannot call organization endpoints. Either call is refused with permission_denied.

Creating and editing a key

Only organization admins can create, edit and delete organization API keys. An organization can have up to 10.

1. In the Soniox Console, open your organization and go to Settings > Organization 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.

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

Permissions

Each organization API key has its own list of permissions, one for each area of the Organization API listed in the overview. They are separate from project API key permissions.

The Project API keys permission has two levels. Read allows listing. Write also allows creating and deleting. The other permissions are either on or off.

Making requests

Send the key as a bearer token, the same way as a project API key:

curl https://api.soniox.com/v1/organization/balance \
  -H "Authorization: Bearer $SONIOX_ORG_API_KEY"

Organization endpoints are served only at https://api.soniox.com. The regional domains refuse them with 400 invalid_request, even when the project is in that domain's region.

All organization endpoints share one rate limit per organization, 50 requests per minute by default. Calls over the limit are refused with 429 limit_exceeded. Project API keys have their own limits, so organization calls do not count against them.

Reading usage

Monthly usage is the cost of one calendar month, for the organization and each project, next to the budget it is measured against. It includes requests made in the Soniox Console playground as well as API requests, because it is the number the budget check uses. api_usage_usd and playground_usage_usd split it by where the requests came from.

The usage summary is totaled per UTC day, per project and per model. It has the same shape, window rules and api_cost_usd / playground_cost_usd split as the project usage summary.

Projects that have since been deleted are included in both reports, so the per-project costs always add up to the total.

Managing project API keys

With Project API keys set to Write, an organization API key can create and delete keys for any project of the organization. List the projects first to get their IDs:

curl https://api.soniox.com/v1/organization/projects \
  -H "Authorization: Bearer $SONIOX_ORG_API_KEY"

Then create a key with the permissions it needs. A project can have up to 10 API keys. Permissions use the resource:level form, with at most one level per resource. See API key permissions for what each one allows.

curl https://api.soniox.com/v1/organization/projects/$PROJECT_ID/api-keys \
  -H "Authorization: Bearer $SONIOX_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "transcription-worker", "permissions": ["stt_async:write", "files:write"]}'

The new key is in the key field of the response. It is returned only once, so store it right away. The created_by field names the organization API key that created it.

To remove a key, call Delete a project API key with its id. Like a deleted organization API key, it may keep working for a few minutes.

Errors