Authentication¶

CloudSync uses API keys for authentication. All communication is encrypted via TLS 1.3.

API Key Types¶

Key Type	Prefix	Permissions	Use Case
Live	`cs_live_`	Full read/write	Production
Test	`cs_test_`	Full read/write (sandbox)	Development
Read-only	`cs_read_`	Read only	Public clients

Setting Your API Key¶

Environment variable (recommended)¶

export CLOUDSYNC_API_KEY="cs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

import os
from cloudsync import CloudSyncClient

client = CloudSyncClient(api_key=os.environ["CLOUDSYNC_API_KEY"])

Direct (not recommended for production)¶

client = CloudSyncClient(api_key="cs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ")

Key Rotation¶

You can rotate keys without downtime:

Generate a new key in the Dashboard
Update your application to use the new key
Deploy
Revoke the old key

Both keys remain valid for a grace period of 24 hours after a new key is generated.

IP Allowlisting¶

Restrict API key usage to specific IP addresses or CIDR ranges:

curl -X POST https://api.example.org/v1/keys/cs_live_.../allowlist \
  -H "Authorization: Bearer cs_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"cidrs": ["203.0.113.0/24", "198.51.100.42/32"]}'

Scoped Tokens¶

For fine-grained access control, generate scoped tokens:

token = client.create_scoped_token(
    documents=["user:12345:*"],
    permissions=["read"],
    ttl=3600  # expires in 1 hour
)
# Share this token with frontend clients

Token Size

Scoped tokens are JWTs and can be up to 2KB. Ensure your transport headers accommodate this.

Next: Error Handling →