Authentication

Every request to the Soku API must be authenticated. The API supports two authentication methods, each used in different contexts. This page covers both methods, when to use each, how to obtain credentials, and how to keep them secure.

Two Authentication Methods

The Soku API uses different authentication depending on the type of endpoint:

Method	Header	Endpoints	Purpose
API Key	`soku-api-key: sk_live_xxxxx`	`/v1/posts`, `/v1/media`, `/v1/templates`, `/v1/ai/transcribe`, `/v1/media/render-og`	All content and automation endpoints
Firebase ID Token	`Authorization: Bearer {id_token}`	`/v1/api-keys`, `/v1/metrics/refresh`	Account management and key administration

These two methods are not interchangeable. Sending an Authorization: Bearer header to a content endpoint (like /v1/posts) will result in a 401 Unauthorized error. Similarly, sending a soku-api-key header to a key management endpoint (like /v1/api-keys) will not work.

Method 1: API Key Authentication

API key authentication is what most developers use. It covers all content endpoints for creating posts, uploading media, rendering templates, and transcribing audio/video.

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.

API Key Format

API keys follow the format sk_live_ followed by a random string, totaling approximately 55 characters:

sk_live_f7e8d9c0b3c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2

Using Your API Key

Include your API key in the soku-api-key header on every content endpoint 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

Method 2: Firebase ID Token Authentication

The API key management endpoints (/v1/api-keys) and the metrics refresh endpoint (/v1/metrics/refresh) use Firebase ID token authentication. This is because creating and revoking API keys is a privileged operation that requires proof of account ownership.

Obtaining a Firebase ID Token

You can obtain a Firebase ID token by authenticating through the Firebase Authentication SDK in your application. See the Firebase documentation for details.

Using an ID Token

Include the Firebase ID token in the Authorization header as a Bearer token:

curl -X POST https://api.mysoku.io/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{"name": "Production Server"}'

Header	Required	Description
`Authorization`	Yes	`Bearer {firebase_id_token}`
`Content-Type`	Yes	Must be `application/json` for requests with a body

Firebase ID tokens expire after 1 hour. Refresh your token before making key management requests if needed.

Quick Reference: Which Auth Method?

I want to…	Endpoint	Auth Method	Header
Create a post	`POST /v1/posts`	API Key	`soku-api-key: sk_live_...`
Upload media	`POST /v1/media`	API Key	`soku-api-key: sk_live_...`
Render a template	`POST /v1/templates`	API Key	`soku-api-key: sk_live_...`
Render an OG image	`POST /v1/media/render-og`	API Key	`soku-api-key: sk_live_...`
Transcribe media	`POST /v1/ai/transcribe`	API Key	`soku-api-key: sk_live_...`
Create an API key	`POST /v1/api-keys`	ID Token	`Authorization: Bearer ...`
List API keys	`GET /v1/api-keys`	ID Token	`Authorization: Bearer ...`
Revoke an API key	`DELETE /v1/api-keys/{id}`	ID Token	`Authorization: Bearer ...`
Refresh metrics	`POST /v1/metrics/refresh`	ID Token	`Authorization: Bearer ...`

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)

If your subscription is not active, the API returns a 403 Forbidden error:

{
  "error": {
    "type": "authentication_error",
    "code": "forbidden",
    "message": "An active subscription is required to access the API.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456",
    "details": null
  }
}

Authentication Errors

Missing or Invalid API Key (401)

If the soku-api-key header is missing or the key is invalid, the API returns a 401 Unauthorized error:

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456",
    "details": null
  }
}

Common causes:

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`
Using `Authorization: Bearer` on a content endpoint	Switch to `soku-api-key` header

Missing or Invalid ID Token (401)

If the Authorization header is missing or the Firebase ID token is invalid on a key management endpoint:

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Invalid or expired Firebase ID token.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456",
    "details": null
  }
}

Common causes:

Problem	Solution
Token has expired	Refresh your Firebase ID token (they expire after 1 hour)
Token is malformed	Verify you are passing a valid JWT from Firebase Auth
Using `soku-api-key` on a key management endpoint	Switch to `Authorization: Bearer {id_token}`

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 using the key management endpoints with Firebase ID token authentication.

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

API Reference

​Authentication

​Two Authentication Methods

​Method 1: API Key Authentication

​Obtaining an API Key

​API Key Format

​Using Your API Key

​Method 2: Firebase ID Token Authentication

​Obtaining a Firebase ID Token

​Using an ID Token

​Quick Reference: Which Auth Method?

​Subscription Requirement

​Authentication Errors

​Missing or Invalid API Key (401)

​Missing or Invalid ID Token (401)

​API Key Security Best Practices

​Store keys in environment variables

​Never expose keys in client-side code

​Use separate keys for each environment

​Rotate keys periodically

​Restrict access

​API Key Management Endpoints

​Request Tracking

​Next Steps

Authentication

Two Authentication Methods

Method 1: API Key Authentication

Obtaining an API Key

API Key Format

Using Your API Key

Method 2: Firebase ID Token Authentication

Obtaining a Firebase ID Token

Using an ID Token

Quick Reference: Which Auth Method?

Subscription Requirement

Authentication Errors

Missing or Invalid API Key (401)

Missing or Invalid ID Token (401)

API Key Security Best Practices

Store keys in environment variables

Never expose keys in client-side code

Use separate keys for each environment

Rotate keys periodically

Restrict access

API Key Management Endpoints

Request Tracking

Next Steps