Authentication

Convoy uses API key authentication to provide secure, multi-tenant access to the batch processing API.

Getting Your API Key

API keys are provisioned directly from the Convoy dashboard at cnvy.ai :

1. Sign in to your account at cnvy.ai 
2. Navigate to your project
3. Go to API Keys and create a new key
4. Copy the key — it is shown only once

Projects

Projects provide multi-tenant isolation in Convoy. Each project:

• Has a unique slug (e.g., my-project) for identification
• Contains its own set of API keys
• Owns its cargo requests — requests are scoped to the project that created them
• Can be activated/deactivated without deleting data

API Keys

API keys authenticate requests to the cargo operations endpoints (/cargo/load, /cargo/{id}/tracking).

Key Format

Keys follow the format: convoy_sk_ followed by 32 random characters.

convoy_sk_7kX9mP2nQ4rT6vW8yB0cD3fG5hJ
└──────┘ └────────────────────────────┘
 prefix          random part

Key Lifecycle

1. Creation — Provisioned via the Convoy dashboard
2. Distribution — Full key shown once at creation; store securely
3. Usage — Include in X-API-Key header for cargo operations
4. Tracking — last_used_at updated on each use
5. Expiration — Optional expiration date
6. Revocation — Keys can be deactivated without deletion

Key Properties

Making Authenticated Requests

Include your API key in the X-API-Key header:

curl -X POST https://api.cnvy.ai/cargo/load \
  -H "Content-Type: application/json" \
  -H "X-API-Key: convoy_sk_your_key_here" \
  -d '{
    "params": {"model": "claude-sonnet-4-5", "messages": [...]},
    "callback_url": "https://example.com/callback"
  }'

Authenticated Endpoints

Error Responses

401 Unauthorized

Returned when authentication fails:

{"detail": "API key required. Include X-API-Key header."}
{"detail": "Invalid API key format."}
{"detail": "Invalid API key."}
{"detail": "API key has expired."}

403 Forbidden

Returned when the project is inactive:

{"detail": "Project is inactive."}

404 Not Found

Returned when accessing cargo not owned by the authenticated project:

{"detail": "Cargo not found"}

Best Practices

1. Use separate keys per environment — Create distinct keys for development, staging, and production
2. Set expiration dates — For temporary access or contractor keys
3. Rotate keys periodically — Create new key, update clients, revoke old key
4. Monitor usage — Check last_used_at to identify unused keys
5. Use HTTPS — Always use TLS to protect keys in transit