Authentication | Speechify API

Overview

Speechify AI API supports two mechanisms for authenticating your requests: API Keys and Access Tokens. Each has specific use cases for properly securing your API calls.

Always use the appropriate authentication method based on your application type to ensure maximum security.

You must authenticate the end-users of your application to control and secure API usage through your account. Unauthenticated access allows anyone to make requests at your expense.

API Keys

Access Tokens

API Keys are randomly generated strings that you can obtain through the dashboard. They are:

Easy to implement
Long-living (no refreshing required)
Immediately revocable if exposed

However, API Keys:

Have full permissions, including destructive operations
Are not suitable for public clients (web frontends, mobile apps)
Require database lookups for validation

API Keys

What are API Keys

API Keys are randomly generated strings obtained through the dashboard. Each key is stored in the database and linked to your account.

When to Use API Keys

Recommended Use Cases

Use API Keys when all of these conditions are met: - Your application is a confidential client (runs entirely on the server) - Your application doesn’t expose Speechify-related calls to users directly or indirectly Example: A call center application sending Speechify requests from the server and playing audio back to users over the phone. Additionally, API Keys are required to issue Access Tokens for your users.

When NOT to Use API Keys

Never use API Keys: - Directly from frontend applications - Directly from mobile or desktop apps - Through unauthenticated proxy endpoints Using API Keys in public clients exposes them to potential attackers, giving full access to: - Create/delete personal voices under your name - Generate audio at your expense No security measure (config endpoints, encryption, etc.) can fully protect API Keys in public clients.

Proxy Considerations

While a proxy can hide your API Key from clients, it introduces new security challenges.

A typical proxy implementation:

Stores the API Key securely on your server
Creates a proxy endpoint (e.g., /speechify-proxy)
Receives client requests and adds the Authorization header
Forwards requests to Speechify AI API
Returns responses to the client

This approach has significant drawbacks:

Without user authentication, anyone can use your proxy
Adds latency to requests
Increases your hosting costs (double traffic)

To implement a secure proxy:

Create specialized endpoints (not wildcard proxies)
Authenticate your users and validate authentication on proxy endpoints

Storing API Keys Securely

Follow these security practices:

Never store keys in source code, even in private repositories
Don’t commit .env files to repositories (add to .gitignore)
Use hosting platform secret management tools:

Using API Keys

Add your API Key to the authorization header when making requests:

Authorization: Bearer YOUR_API_KEY

This applies to all requests, including those to issue access tokens.

Access Tokens

What are Access Tokens

Access tokens authenticate API calls similar to API Keys but with important differences:

Access Tokens are JSON Web Tokens (JWTs) that:

Embed account information and token properties (lifetime, scope)
Are cryptographically signed for validation without database lookups
Have limited lifetimes to minimize exposure risk
Can be scoped to specific permissions

When to Use Access Tokens

Recommended Use Cases

Always use Access Tokens when:

Your code runs in public clients (browsers, mobile apps)
You need to limit permissions for specific operations

Access Tokens provide necessary security while allowing direct API communication, saving server costs.

Access Tokens offer advantages for all use cases:

Short-lived (limited exposure window)
Permission-scoped (prevents unintended operations)
Faster validation (no database lookups)

When NOT to Use Access Tokens

Unlike API Keys, there are very few limitations to using Access Tokens. They can be used for virtually any request to the Speechify AI API, with only these exceptions:

You cannot use Access Tokens to issue other Access Tokens (you must use an API Key for this)
If you need the ability to immediately revoke authentication (Access Tokens must expire naturally)

In most scenarios, Access Tokens are the preferred authentication method, especially for public clients.

How to Use Access Tokens

Speechify follows the OAuth 2.0 Client Credentials flow for access tokens.

Issue the Token

Make a POST request to https://api.sws.speechify.com/v1/auth/token:

$ curl -X POST https://api.sws.speechify.com/v1/auth/token \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=client_credentials&scope=audio:speech"

The request:

Must be authorized with your API Key
Requires grant_type=client_credentials
Can include optional scope parameter

Response:

1 {
2   "access_token": "abc.def.xyz",
3   "token_type": "bearer",
4   "expires_in": 3600,
5   "scope": "audio:speech"
6 }

Authorize Requests

Use the token in your authorization header:

Authorization: Bearer your.access.token

Refresh Tokens

Since tokens expire, implement a refresh strategy:

Request a token when users authenticate
Store the token in memory
Create a reusable method to retrieve the token
Schedule token refresh before expiration (e.g., halfway through lifetime)
Continue refreshing as needed
Clear tokens when users log out

Access Token Scopes

When requesting tokens, you can specify permission scopes:

1 const singleScope = "audio:speech"; // single scope
2 const multipleScopes = "audio:speech voices:read"; // space-separated multiple scopes

Available scopes:

Scope	Description
`audio:speech`	Generate speech audio
`audio:stream`	Stream speech audio
`audio:all`	All audio operations
`voices:read`	List available voices
`voices:create`	Create personal voices
`voices:delete`	Delete personal voices
`voices:all`	All voice operations

The default scope is audio:all voices:read if not specified.

If you attempt an operation without the required scope, the request will be rejected with a 401 Unauthorized error.

Importance of End-User Authentication

Without proper end-user authentication, anyone can make API requests at your expense. This is true for any distributed system, not just Speechify AI API.

For example, in a web application with a TTS feature, unauthenticated users could make unlimited API requests with the same or altered inputs, potentially causing unexpected costs.