API Keys

The API Keys endpoints let you programmatically create, list, and revoke API keys for your Soku account. These endpoints are intended for building custom admin dashboards, automation tooling, or key rotation scripts.

The API key management endpoints use Firebase ID token authentication, not the soku-api-key header used by content endpoints. You must include a valid Firebase ID token in the Authorization header as a Bearer token.

Authentication for Key Management

Unlike the content endpoints (posts, media, templates, transcription) which use the soku-api-key header, the API key management endpoints authenticate using a Firebase ID token. This is because creating and revoking API keys is a privileged operation that requires proof of account ownership. Include the Firebase ID token in the Authorization header:

Authorization: Bearer <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.

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

Create an API Key

Create a new API key for your account.

POST /v1/api-keys

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Authorization`	Yes	`Bearer <firebase-id-token>`

Request Body

Field	Type	Required	Description
`name`	string	No	A descriptive name for the API key (for example, “Production Server”, “CI Pipeline”).

Response

Status: 201 Created

Field	Type	Description
`apiKey`	string	The full API key value. This is the only time the complete key is returned.

{
  "apiKey": "sk_live_f7e8d9c0b3c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2"
}

The apiKey field contains the full API key and is only returned at creation time. Store it securely immediately. If you lose the key, you must revoke it and create a new one.

Example

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

List API Keys

Retrieve all API keys associated with your account. For security, the full key value is not returned — only metadata including the key ID, name, creation date, and a masked preview of the key.

GET /v1/api-keys

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <firebase-id-token>`

Response

Returns an object containing an array of API key metadata objects.

Field	Type	Description
`keys`	array	Array of API key metadata objects
`keys[].id`	string	The unique ID of the API key
`keys[].name`	string	The descriptive name given to the key
`keys[].tokenPreview`	string	A masked preview of the key value (for example, `sk_live_f7e8...3456`)
`keys[].createdAt`	string	ISO 8601 timestamp of when the key was created
`keys[].revokedAt`	string or null	ISO 8601 timestamp of when the key was revoked, or `null` if still active

{
  "keys": [
    {
      "id": "key_a1b2c3d4",
      "name": "Production Server",
      "tokenPreview": "sk_live_f7e8...3456",
      "createdAt": "2026-02-28T12:00:00.000Z",
      "revokedAt": null
    },
    {
      "id": "key_e5f6a7b8",
      "name": "Staging Server",
      "tokenPreview": "sk_live_a1b2...7890",
      "createdAt": "2026-02-20T10:00:00.000Z",
      "revokedAt": null
    },
    {
      "id": "key_c9d0e1f2",
      "name": "Old Key",
      "tokenPreview": "sk_live_c3d4...1234",
      "createdAt": "2026-01-15T09:00:00.000Z",
      "revokedAt": "2026-02-01T14:00:00.000Z"
    }
  ]
}

Example

curl -X GET https://api.mysoku.io/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Revoke an API Key

Permanently revoke an API key. Once revoked, any requests using this key will receive a 401 Unauthorized response. This action cannot be undone.

DELETE /v1/api-keys/{id}

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <firebase-id-token>`

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the API key to revoke

Response

Status: 200 OK

{
  "revoked": true
}

Example

curl -X DELETE https://api.mysoku.io/v1/api-keys/key_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Key Rotation Workflow

To rotate an API key without downtime:

Create a new API key using POST /v1/api-keys.
Update your application or service to use the new key.
Verify that requests are succeeding with the new key.
Revoke the old key using DELETE /v1/api-keys/{id}.

# Step 1: Create a new key
NEW_KEY=$(curl -s -X POST https://api.mysoku.io/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -d '{"name": "Production Server (rotated)"}' \
  | jq -r '.apiKey')

echo "New key created"

# Step 2: Update your application to use $NEW_KEY
# (application-specific step)

# Step 3: Verify the new key works by making a test request
curl -s -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $NEW_KEY" \
  -d '{
    "post": {
      "content": {
        "text": "Key rotation test",
        "mediaType": "text",
        "platform": ["threads"]
      }
    }
  }'

# Step 4: Revoke the old key
curl -X DELETE https://api.mysoku.io/v1/api-keys/key_old_id_here \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Error Responses

HTTP Status	Error Code	Description
400	`validation_error`	Missing or invalid `name` field
401	`unauthorized`	Missing or invalid Firebase ID token
403	`forbidden`	Subscription is not active
404	`not_found`	The specified key ID does not exist
429	`rate_limit_exceeded`	Too many requests. See Rate Limits.
500	`internal_error`	An internal error occurred

Example error response:

{
  "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
  }
}

Next Steps

Topic	Description
Authentication	How to use API keys in requests
API Key Management (Dashboard)	Manage keys through the Soku dashboard
Rate Limits	Understand request limits

API Reference

Api keys

API Keys

Authentication for Key Management

Create an API Key

Headers

Request Body

Response

Example

List API Keys

Headers

Response

Example

Revoke an API Key

Headers

Path Parameters

Response

Example

Key Rotation Workflow

Error Responses

Next Steps

​API Keys

​Authentication for Key Management

​Create an API Key

​Headers

​Request Body

​Response

​Example

​List API Keys

​Headers

​Response

​Example

​Revoke an API Key

​Headers

​Path Parameters

​Response

​Example

​Key Rotation Workflow

​Error Responses

​Next Steps

API Keys

Authentication for Key Management

Create an API Key

Headers

Request Body

Response

Example

List API Keys

Headers

Response

Example

Revoke an API Key

Headers

Path Parameters

Response

Example

Key Rotation Workflow

Error Responses

Next Steps