Skip to main content

​
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 all other endpoints. You must include a valid Firebase ID token in the Authorization header as a Bearer token.

​
Authentication for Key Management

Unlike other Soku API endpoints, 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.

​
Create an API Key

Create a new API key for your account. 
POST /v1/api-keys

​
Headers

HeaderRequiredDescription
Content-TypeYesMust be application/json
AuthorizationYesBearer <firebase-id-token>

​
Request Body

FieldTypeRequiredDescription
namestringNoA descriptive name for the API key (1-100 characters). For example, “Production Server”, “CI Pipeline”.

​
Response

FieldTypeDescription
apiKeystringThe full API key value. This is the only time the complete key is returned.
{
  "apiKey": "sk_live_f7e8d9c0b3c4d5e6a7b8c9d0e1f23456"
}
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, and creation date. 
GET /v1/api-keys

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <firebase-id-token>

​
Response

Returns an object containing an array of API key metadata objects. Each key includes a tokenPreview field showing a masked preview of the key value. 
{
  "keys": [
    {
      "id": "key_a1b2c3d4",
      "name": "Production Server",
      "tokenPreview": "sk_live_f7e8...3456",
      "createdAt": "2026-02-28T12:00:00.000Z",
      "lastUsedAt": "2026-02-28T15:30:00.000Z"
    },
    {
      "id": "key_e5f6a7b8",
      "name": "Staging Server",
      "tokenPreview": "sk_live_a1b2...7890",
      "createdAt": "2026-02-20T10:00:00.000Z",
      "lastUsedAt": "2026-02-27T08:15:00.000Z"
    },
    {
      "id": "key_c9d0e1f2",
      "name": "GitHub Actions",
      "tokenPreview": "sk_live_c3d4...1234",
      "createdAt": "2026-01-15T09:00:00.000Z",
      "lastUsedAt": null
    }
  ]
}

​
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

HeaderRequiredDescription
AuthorizationYesBearer <firebase-id-token>

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesThe ID of the API key to revoke

​
Response

Returns a JSON object with HTTP status 200 OK on success. 
{
  "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:
  1. Create a new API key using POST /v1/api-keys.
  2. Update your application or service to use the new key.
  3. Verify that requests are succeeding with the new key.
  4. 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: $NEW_KEY"

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

# Step 3: Verify the new key works
curl -s -X GET https://api.mysoku.io/v1/repurposeLinks \
  -H "soku-api-key: $NEW_KEY"

# 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 StatusError CodeDescription
400validation_errorMissing or invalid name field
401unauthorizedMissing or invalid Firebase ID token
403forbiddenSubscription is not active
404not_foundThe specified key ID does not exist
429rate_limit_exceededToo many requests. See Rate Limits.
500internal_errorAn internal error occurred
Example error response: 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired Firebase ID token.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456"
  }
}

​
Next Steps

TopicDescription
AuthenticationHow to use API keys in requests
API Key Management (Dashboard)Manage keys through the Soku dashboard
Rate LimitsUnderstand request limits