Authentication

API keys and authorization

All API requests require authentication via API key or JWT.

API Key

Create API keys from Dashboard → API Keys.

Authorization: Bearer cdv_your_api_key_here

Dual Authentication

The API supports two authentication methods:

Method	Header	Use Case
API Key	Authorization: Bearer cdv_xxx	External integrations, automation
JWT (Supabase)	Authorization: Bearer eyJ...	Dashboard UI, white-label

API keys are workspace-scoped — they can access all profiles within the workspace.

Keeping Your Credentials Safe

Never share your API key publicly. Treat it like a password — anyone with your key can publish content, manage accounts, and access all data in your workspace.

Use environment variables. Store keys in .env files or your platform's secret manager (Vercel, AWS Secrets, etc.). Never commit keys to version control.

Server-side only. API calls should always originate from your backend. Never include API keys in frontend JavaScript, mobile apps, or browser-accessible code.

Rotate regularly. Create new keys periodically and revoke old ones from Dashboard → API Keys. If a key may have been exposed, revoke it immediately.

Data Protection

CodivUpload takes your data security seriously:

All API traffic is encrypted via HTTPS/TLS.
OAuth tokens for connected platforms are encrypted at rest (AES-256-GCM).
API keys are stored as SHA-256 hashes — we cannot retrieve your original key after creation.
All data processing complies with our Privacy Policy and Terms of Service.

Rate Limits

If a platform temporarily blocks publishing, the post is automatically retried. You don't need to resend the request.

Rate Limit Details

Limit Type	Value	Notes
API requests	100 requests / minute per API key	Applies to all /v1/* endpoints combined
Platform publishing	Varies per platform	See Platform Limits for daily post caps
Media uploads	50 uploads / hour per workspace	Applies to /v1/upload-media

When you exceed the API request rate limit, the response includes a Retry-After header indicating how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "Rate limit exceeded. Try again in 42 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Key Compromise Recovery

If you suspect your API key has been exposed or compromised, act immediately:

Revoke the key: Go to Dashboard → API Keys, find the compromised key, and click Delete. Revocation is immediate — all requests using that key will fail within seconds.
Create a new key: Generate a replacement key from the same page.
Update all integrations: Replace the old key in your environment variables, MCP config, and any third-party services that used it.
Audit recent activity: Review your post history in the Dashboard for any posts you didn't create. If unauthorized posts were published, remove them from each platform directly.

Remember: API keys are stored as SHA-256 hashes. We cannot retrieve your original key — if you lose it, create a new one.

Multiple API Keys

You can create multiple API keys per workspace. Each key has full workspace access but can be independently revoked. Recommended strategy:

Key Name	Used For
app-production	Your main application or backend service
mcp-claude	MCP server connection for AI assistants
automation-n8n	n8n / Make / Zapier automation workflows
staging	Test environment (rotate freely)

Using separate keys per integration means a compromise only affects that one integration. You can revoke and replace it without disrupting the others.

For the full interactive API reference, visit api.codivupload.com.