API Authentication

Sonna provides two ways to authorize REST API requests. While the web and Android apps use JSON Web Tokens (JWT) (via Google login) to run UI sessions, developers calling the REST API directly should use API Keys.

Developer Credit Discount

Authenticating requests with an API Key automatically applies a 10% credit discount on Speech generations. Calls authenticated with a JWT are charged the full UI/app rate.

Getting an API Key

API keys can only be created by paying users (those with an active Pro or Max subscription, or a positive Pay-As-You-Go (PAYG) credit balance). Users on the Free plan do not have API access and cannot create keys.

To manage your API keys, use the self-service endpoints:

1. Create a Key

To mint a new API key, make a POST request to the API key creation endpoint. You can optionally name your key.

Request:

curl -X POST https://api.sonnalabs.app/api/v1/user/api-keys \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server"
  }'

Response (201 Created):

{
  "success": true,
  "key": "sona_sk_6b3d9...c27a",
  "apiKey": {
    "id": "e30e1762-cb07-4f6c-8517-3bf777e5d8ea",
    "keyPrefix": "sona_sk_6b3d9",
    "name": "Production Server",
    "createdAt": "2026-06-10T17:44:05.000Z",
    "lastUsedAt": null,
    "revokedAt": null
  }
}

Store Your Key Safely

The plaintext key returned in the key field is only shown once. The server only stores a SHA-256 hash of the key for verification and cannot retrieve or show the plaintext secret to you again. Copy and save it immediately.

Each user can have a maximum of 10 active API keys at any time.

2. List Your Keys

You can list all active and revoked API keys associated with your account. This is useful for monitoring usage and managing access.

Request:

curl -X GET https://api.sonnalabs.app/api/v1/user/api-keys \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Response (200 OK):

{
  "success": true,
  "apiKeys": [
    {
      "id": "e30e1762-cb07-4f6c-8517-3bf777e5d8ea",
      "keyPrefix": "sona_sk_6b3d9",
      "name": "Production Server",
      "createdAt": "2026-06-10T17:44:05.000Z",
      "lastUsedAt": "2026-06-10T17:45:00.000Z",
      "revokedAt": null
    }
  ]
}

3. Revoke a Key

If an API key is compromised, or you no longer need it, you can revoke it. Once revoked, the key becomes permanently invalid.

Request:

curl -X DELETE https://api.sonnalabs.app/api/v1/user/api-keys/e30e1762-cb07-4f6c-8517-3bf777e5d8ea \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>"

Response (200 OK):

{
  "success": true
}

Authenticating REST API Requests

Once you have your API key (formatted as sona_sk_ followed by a random base64url secret), you can authenticate your requests by providing it in either of these HTTP headers:

Option A: Authorization Header (Bearer)

Authorization: Bearer sona_sk_6b3d9...c27a

Option B: Custom X-API-Key Header

X-API-Key: sona_sk_6b3d9...c27a

Either header option is fully valid. Choose the one that fits best with your API client or library constraints.

Security Best Practices

Keep your Token Secure

Your API key grants access to generate media and spend your account's credits. Never expose it in client-side code repositories, public websites, or check it into Git.

Store in Environment Variables: Keep your API keys in environment variables (e.g., SONNA_API_KEY) on your server. Do not hardcode them in your codebase.
Revoke Compromised Keys: If a key is accidentally exposed, immediately revoke it via the keys dashboard or the DELETE /api/v1/user/api-keys/:id endpoint and mint a new one.
Role Restrictions: Developer API keys authenticate your user account. Endpoints prefixed with /api/admin/* and internal cron jobs are restricted and cannot be accessed using developer API keys.

On this page