Skip to main content

Authentication

All ViralSync API requests must include an API key. This page covers creating keys, using them in requests, and keeping them secure.

Creating an API key​

  1. Log in to the ViralSync Dashboard
  2. Go to Settings → API Keys
  3. Click Create New Key
  4. Give it a descriptive name (e.g., "n8n Production", "Backend Service")
  5. Copy the key immediately — it is only shown in full once

API keys have the format vs_prod_ followed by a random string:

vs_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using your API key​

curl -H "x-api-key: vs_prod_YOUR_API_KEY" \
     https://api.viralsync.io/v1/me

Method 2: Authorization: Bearer header​

curl -H "Authorization: Bearer vs_prod_YOUR_API_KEY" \
     https://api.viralsync.io/v1/me

Both methods are equivalent. The x-api-key header is recommended because it is more explicit and avoids ambiguity with other Bearer token schemes.

Environment variable best practice​

Never hardcode API keys in source code. Use environment variables:

# .env (never commit this file)
VIRALSYNC_API_KEY=vs_prod_YOUR_API_KEY
# Shell usage
export VIRALSYNC_API_KEY="vs_prod_YOUR_API_KEY"

curl -H "x-api-key: $VIRALSYNC_API_KEY" \
     https://api.viralsync.io/v1/render/jobs \
     -d @payload.json
// Node.js
const apiKey = process.env.VIRALSYNC_API_KEY;
# Python
import os
api_key = os.environ['VIRALSYNC_API_KEY']

Verify your key​

Test that a key is valid with a simple request to /v1/me:

curl -s -H "x-api-key: $VIRALSYNC_API_KEY" \
     https://api.viralsync.io/v1/me

Success (200 OK):

{
  "userId": "user_abc123",
  "plan": "pro",
  "email": "you@example.com"
}

Security best practices​

Keep keys secret. Never include API keys in:

  • Client-side JavaScript (browser bundles)
  • Mobile app binaries
  • Public GitHub repositories
  • Log files or error tracking systems

Use environment variables (.env files, secrets managers like AWS Secrets Manager, Vault, or Vercel environment variables).

Rotate keys regularly. Create a replacement key, update your services, then revoke the old key. Revocation is immediate.

Use separate keys per environment. Create a key named "staging" and a separate key named "production" so you can revoke one without affecting the other.

Scope awareness. Currently all API keys grant full access to your account's resources. Scoped keys (read-only, render-only, etc.) are on the roadmap.

Error responses​

401 Unauthorized — invalid or missing key​

{
  "error": "Missing or invalid API key.",
  "code": "UNAUTHORIZED"
}

Causes: missing x-api-key header, typo in the key, key was deleted.

401 Unauthorized — key revoked​

{
  "error": "This API key has been revoked.",
  "code": "API_KEY_REVOKED"
}

Go to Dashboard → Settings → API Keys and create a new key.

403 Forbidden — plan restriction​

{
  "error": "API access is not available on the Free plan. Upgrade to Pro.",
  "code": "FORBIDDEN"
}

The API key is valid but your plan does not include API access. Upgrade to Pro →