Authentication

All API requests authenticate with a secret API key passed as a Bearer token.

API keys

WeaveOS uses secret API keys for authentication. Each key is scoped to an environment — live or test. Keys can be created, rotated, and revoked from Dashboard → Developer → API Keys.

Include the key as a Bearer token in the Authorization header of every request:

curl https://api.weaveos.dev/v1/workflows \
  -H "Authorization: Bearer sk_test_abc123..."

Key management

Best practices for managing API keys:

• Store keys in environment variables or a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault).
• Create separate keys per service or deployment environment.
• Set a descriptive name when creating a key so you can identify it later.
• Rotate keys periodically — the dashboard shows each key's last used timestamp to help identify stale keys.
• Revoke keys that are no longer in use.

Rate limits

API requests are rate-limited per API key. Exceeding the limit returns a 429 Too Many Requests response. The response includes headers indicating your current usage and when the limit resets.

# Rate limit headers returned on every response
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1716892800

Implement exponential backoff when handling 429 responses. The SDK retries automatically with jitter.

Request timeouts

The API enforces a 30-second timeout on all requests. Long-running workflow operations are handled asynchronously — workflows.create()returns immediately with the workflow ID and quoted price, while execution proceeds in the background and results are delivered via webhooks.

TLS

All API traffic must use HTTPS. Requests over plain HTTP are rejected with a redirect. The minimum TLS version is 1.2; TLS 1.3 is preferred.