Authentication

Convotic supports two authentication methods depending on your use case.

Method	Use case	Mechanism
Dashboard	Browser-based access	JWT issued via Google OAuth
API	Server-to-server calls	X-API-Key header

Dashboard authentication (JWT)

When you sign in at app.convotic.com, Convotic authenticates you via Google OAuth 2.0 and issues a short-lived JWT. The dashboard handles token refresh automatically -- no action is required on your part.

JWTs are scoped to your user and workspace. They are stored in an HTTP-only cookie and are not accessible to client-side JavaScript.

API authentication (X-API-Key)

For programmatic access, use an API key passed in the X-API-Key request header.

Generating an API key

1. Open the Convotic dashboard.
2. Navigate to Settings > API Keys.
3. Click Create API Key.
4. Give the key a descriptive name (e.g., production-backend).
5. Copy the key immediately -- it will not be shown again.

警告

API keys grant full access to your workspace. Treat them like passwords. Rotate keys periodically and revoke any that may have been compromised.

Using your API key

cURL

curl https://api.convotic.com/v1/contacts \
  -H "X-API-Key: cvtk_live_your_api_key_here" \
  -H "Content-Type: application/json"

TypeScript

const API_KEY = process.env.CONVOTIC_API_KEY;

async function listContacts() {
  const response = await fetch("https://api.convotic.com/v1/contacts", {
    method: "GET",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

Error responses

If authentication fails, the API returns one of the following:

Status	Body	Meaning
401 Unauthorized	{ "error": "missing_api_key" }	No X-API-Key header was provided.
401 Unauthorized	{ "error": "invalid_api_key" }	The key is malformed or has been revoked.
403 Forbidden	{ "error": "insufficient_permissions" }	The key does not have access to the requested resource.

Rate limits

API requests are rate-limited per workspace. The current limits are returned in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1711900800

If you exceed the limit, the API returns 429 Too Many Requests. Back off and retry after the X-RateLimit-Reset timestamp.

Best practices

• Use environment variables or a secrets manager to store API keys.
• Create separate keys for each service or environment (staging, production).
• Revoke unused keys promptly.
• Monitor API key usage in Settings > API Keys > Usage.