Authentication
Every request to the Soku API must be authenticated. The primary authentication method is an API key passed in a custom request header. This page covers how to obtain an API key, how to include it in requests, and how to keep it secure.
Obtaining an API Key
API keys are created in the Soku dashboard:
- Log in to your account at mysoku.io.
- Navigate to Settings > API Keys.
- Click Create API Key.
- Give the key a descriptive name (for example, “Production Server” or “CI Pipeline”).
- Copy the key immediately. For security, the full key is only shown once at creation time.
Copy your API key when it is first displayed. You will not be able to view the full key again after leaving the creation screen. If you lose a key, revoke it and create a new one.
Using Your API Key
Include your API key in the soku-api-key header on every request:
curl -X POST https://api.mysoku.io/v1/posts \
-H "Content-Type: application/json" \
-H "soku-api-key: sk_live_your_api_key_here" \
-d '{
"post": {
"content": {
"text": "Hello from the API",
"mediaType": "text",
"platform": ["threads"]
}
}
}'
| Header | Required | Description |
|---|
soku-api-key | Yes | Your Soku API key, starting with sk_live_ |
Content-Type | Yes | Must be application/json for all requests with a body |
Subscription Requirement
API access requires an active Soku subscription. Your account must be in one of the following states:
| Subscription Status | API Access |
|---|
| Trialing (free trial active) | Allowed |
| Active (paid subscription) | Allowed |
| Canceled | Denied (403) |
| Expired | Denied (403) |
| Past due | Denied (403) |
403 Forbidden error:
{
"error": {
"code": "forbidden",
"message": "An active subscription is required to access the API.",
"timestamp": "2026-02-28T12:00:00.000Z",
"requestId": "req_abc123def456"
}
}
Authentication Errors
If the soku-api-key header is missing or the key is invalid, the API returns a 401 Unauthorized error:
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key.",
"timestamp": "2026-02-28T12:00:00.000Z",
"requestId": "req_abc123def456"
}
}
| Problem | Solution |
|---|
| Header is missing entirely | Add the soku-api-key header to your request |
| Key is misspelled or truncated | Verify you copied the full key, including the sk_live_ prefix |
| Key has been revoked | Create a new key in Settings > API Keys |
| Wrong header name | Use soku-api-key, not Authorization or x-api-key |
API Key Security Best Practices
API keys grant full access to your Soku account through the API. Treat them with the same care as passwords.
Store keys in environment variables
Never hard-code API keys in source code, configuration files checked into version control, or client-side code.
# Set as an environment variable
export SOKU_API_KEY="sk_live_your_api_key_here"
// Read from environment
const apiKey = process.env.SOKU_API_KEY;
Never expose keys in client-side code
API keys must only be used in server-side code. Never include them in frontend JavaScript, mobile apps, or any code that runs in a browser. If you need to make API calls from a client application, proxy them through your own backend server.
If an API key is exposed publicly (for example, committed to a public repository), revoke it immediately in Settings > API Keys and create a replacement.
Use separate keys for each environment
Create distinct API keys for development, staging, and production. This lets you revoke a compromised key without affecting other environments.
| Environment | Key Name Example |
|---|
| Development | Dev Server - Local |
| Staging | Staging Server |
| Production | Production Backend |
| CI/CD | GitHub Actions Pipeline |
Rotate keys periodically
Revoke and replace API keys on a regular schedule, even if you have no reason to believe they have been compromised. This limits the window of exposure if a key is leaked without your knowledge.
Restrict access
Only share API keys with team members and services that need them. Audit your active keys periodically in Settings > API Keys and revoke any that are no longer in use.
API Key Management Endpoints
You can also create, list, and revoke API keys programmatically. These endpoints use Firebase ID token authentication instead of the soku-api-key header.
For details on the API key management endpoints, see API Keys.
Request Tracking
Every API response includes an X-Request-ID header that uniquely identifies the request. Include this value when contacting support about a specific request.
X-Request-ID: req_abc123def456
Next Steps
| Topic | Description |
|---|
| Posts API | Start creating and publishing posts |
| API Keys | Manage API keys programmatically |
| Rate Limits | Understand request limits for your tier |
