API Authentication Issues

"Unauthorized" (401)

Invalid API key

• Verify the key starts with vk_sk_
• Keys are shown only once at creation — if lost, create a new one
• Check for trailing whitespace or newline characters

Missing header

Include the key as a Bearer token:

curl https://vulk.dev/api/v1/projects \
  -H "Authorization: Bearer vk_sk_your_key_here"

"Forbidden" (403)

Insufficient permissions

Each API key has scoped permissions. Check which permissions your key has in Settings > API Keys:

• projects:read — List and view projects
• projects:write — Create and edit projects
• deploy:write — Deploy projects
• export:read — Download project code

Plan limitation

API access requires Pro plan or higher. Builder and free accounts cannot use the API.

"Rate Limited" (429)

You have exceeded your rate limit. The response includes:

{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}

Wait the indicated seconds before retrying. Rate limits per plan:

• Pro: 300/min
• Team: 500/min
• Business: 1,000/min

Check remaining quota

Every API response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1712073600

CORS Errors

The VULK API does not support browser-based requests (CORS). Use the API from server-side code, CLI tools, or MCP integrations only.

API Key Best Practices

• Create separate keys for different environments (dev, staging, production)
• Use the minimum permissions needed
• Rotate keys periodically
• Never commit API keys to version control
• Use environment variables to store keys