Authentication
Learn how to authenticate with the Soke API using API keys or JWT tokens.
Authentication Methods
Soke supports two authentication methods depending on your use case.
API Key (recommended for integrations)
Use an API key for server-to-server integrations, automation tools (n8n, Make, Zapier), and scripts. Pass your key in the X-Soke-Key header:
curl -X POST https://api.usesoke.ai/api/v1/research/keywords \
-H "Content-Type: application/json" \
-H "X-Soke-Key: sk_live_your_api_key" \
-d '{"topic": "your topic", "platform": "youtube"}'API keys start with sk_live_ and can be created, rotated, and revoked from your dashboard under Settings > API Keys.
Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests. If a key is compromised, rotate it immediately from your dashboard.
JWT Token (dashboard users)
JWT authentication is used by the Soke dashboard and is available for browser-based integrations. It uses a short-lived access token with a refresh token for renewal.
Step 1: Login to get tokens
curl -X POST https://api.usesoke.ai/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "you@example.com",
"password": "your_password"
}'Response:
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
"expiresAt": "2025-01-15T12:00:00Z"
}
}Step 2: Use the access token
curl -X POST https://api.usesoke.ai/api/v1/research/keywords \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-d '{"topic": "your topic", "platform": "youtube"}'Step 3: Refresh when expired
curl -X POST https://api.usesoke.ai/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "dGhpcyBpcyBhIHJlZnJl..."}'Chat Completions endpoint
The /api/v1/chat/completions endpoint accepts both authentication methods. When using JWT, conversations are persisted and accessible from the dashboard. When using an API key, requests are stateless.
Account selection
If your user account has multiple YouTube accounts connected, specify which account to use with the X-Soke-Account-Id header:
curl -X POST https://api.usesoke.ai/api/v1/research/keywords \
-H "X-Soke-Key: sk_live_your_api_key" \
-H "X-Soke-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{"topic": "your topic", "platform": "youtube"}'If omitted, your default account is used.
Subscription requirement
All API endpoints (except auth, billing, and onboarding) require an active subscription. If your subscription is expired or missing, you'll receive:
{
"success": false,
"error": {
"code": "SUBSCRIPTION_REQUIRED",
"message": "An active subscription is required to access this endpoint."
},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}