Authentication

Every CodeCourier REST API request must be authenticated with a project-scoped API key. This page explains how to create keys, how to include them in requests, and how to handle authentication errors.

Creating an API Key

1. Open your project in the CodeCourier dashboard.
2. Navigate to Project Settings and open the API Keys section.
3. Click Generate New Keyand provide a descriptive name (e.g., "CI Pipeline" or "LLM Agent").
4. The system displays the full key exactly once. Copy it immediately and store it securely. CodeCourier stores only a SHA-256 hash -- the raw key cannot be recovered.

You can also create keys programmatically via the Project API: POST /api/v1/project/api-keys/generate.

API Key Format

All project API keys follow a recognizable prefix format:

cc_live_a1b2c3d4e5f6...   # production key
cc_test_a1b2c3d4e5f6...   # test/staging key

Keys are prefixed with cc_live_ (production) or cc_test_ (test environments). The prefix plus the first 8 characters serve as the display prefix shown in the dashboard. The full key is a long random string used for authentication.

Using the API Key

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

curl -X GET \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  https://<your-deployment>.convex.site/api/v1/project

For POST requests with a JSON body:

curl -X POST \
  -H "Authorization: Bearer cc_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workflow"}' \
  https://<your-deployment>.convex.site/api/v1/workflows/create

Base URL

The base URL is your Convex deployment's HTTP Actions endpoint:

https://<your-deployment>.convex.site/api/v1/

Common mistake: Use .convex.site -- NOT .convex.cloud. The .convex.cloud domain is the internal Convex data WebSocket URL and will not serve REST API requests. Only .convex.site exposes HTTP Actions.

You can find your deployment name in the Convex dashboard (e.g., happy-animal-123), giving a base URL of https://happy-animal-123.convex.site/api/v1/.

Key Properties

• Project-scoped -- Each key is tied to a specific project and can only access resources within that project.
• Named -- Assign human-readable names for easy management.
• Revocable -- Keys can be revoked instantly. Revoked keys immediately stop authenticating.
• Usage-tracked -- The lastUsedAt timestamp updates on each use, helping identify stale keys.

Response Format

All API responses use a consistent JSON envelope:

Success Response

{
  "data": {
    "id": "abc123",
    "name": "My Project",
    ...
  }
}

Error Response

{
  "error": "Human-readable error message"
}

Error Codes

• 400 Bad Request -- Missing required fields, invalid JSON body, or invalid query parameters.
• 403 Forbidden -- Invalid API key, revoked key, or key does not have access to the requested project.
• 404 Not Found -- The requested resource does not exist or has been permanently deleted.
• 500 Internal Server Error -- An unexpected error occurred. The error message is included in the response body.

Managing Keys via API

The API itself provides endpoints for key management (you need an existing key to use these):

• GET /api/v1/project/api-keys -- List all keys for the project (shows prefix, name, dates, status).
• POST /api/v1/project/api-keys/generate -- Generate a new key. Body: { "name": "Key Name" }. Returns the full key (only time it is shown).
• POST /api/v1/project/api-keys/revoke -- Revoke a key. Body: { "keyId": "..." }.

Provider API Keys

Separate from project API keys, CodeCourier manages provider keys for external services used at sandbox runtime (E2B, Anthropic, OpenRouter, OpenAI, GitHub). These are configured through /api/v1/project/provider-keys/* endpoints. All provider keys are encrypted before storage; only the last four characters are stored in plaintext for display.

Security Best Practices

• Never commit API keys to source control. Use environment variables or a secrets manager.
• Rotate keys regularly. Revoke and regenerate keys periodically. The lastUsedAt field helps identify suspicious activity.
• Use descriptive names.Name keys after their use case (e.g., "CI Pipeline", "Staging Agent") so you know which to revoke if compromised.
• Revoke unused keys. Keys that have not been used in months should be revoked.