Authentication

Learn how to authenticate with the Lia API using API keys - generation, security best practices, and troubleshooting.

API Key Authentication

All API requests must include an API key in the x-api-key header:

curl https://api.acolad.ai/whoami \
  -H "x-api-key: YOUR_API_KEY"

Generating API Keys

To generate a new API key, follow the step-by-step guide in the quickstart:

Quickstart

Security Best Practices

Keep Keys Secret

Never expose API keys in client-side code, public repositories, or logs:

// ❌ Bad - Exposed in client-side code
const apiKey = 'lia_sk_abc123...';

// ✅ Good - Use environment variables
const apiKey = process.env.LIA_API_KEY;

Rotate Keys Regularly

Rotate API keys periodically and after any potential security incident:

1

Generate a new API key

Follow the quickstart guide to create a new API key in your workspace settings

2

Update your applications

Deploy the new key to all applications and environments

3

Verify the new key works

Test all API integrations to ensure they work with the new key

4

Delete the old key

Once verified, remove the old key from your workspace settings

Use Descriptive Key Names

Choose clear, descriptive names when generating keys to track their usage:

Production API Server
Staging Environment
CI/CD Pipeline

Limit Key Scope

Generate separate keys for different environments and purposes:

• Production keys for live applications

• Development keys for testing and development

• CI/CD keys for automated pipelines

Use Scoped Permissions

When creating API keys, use scoped access instead of full access when possible:

• Full access: Grants all permissions within the workspace. Use only when necessary.

• Scoped access: Limit permissions to specific actions (e.g., translation only). Recommended for production.

This follows the principle of least privilege and reduces security risks if a key is compromised.

Set Expiration Dates

Configure expiration dates for API keys to automatically revoke access after a set period:

• Short-lived keys: Use for temporary integrations or testing (e.g., 30-90 days)

• Long-lived keys: Use for production with regular rotation schedules

• No expiration: Avoid when possible, or ensure strict rotation policies

Keys with expiration dates reduce the risk window if a key is compromised.

Example Requests

curl

curl https://api.acolad.ai/translate/text \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "targetLang": "fr"}'

JavaScript

Python

Node.js (Axios)

Troubleshooting

Missing API Key

If you don't include an API key, you'll receive a 401 Unauthorized error:

{
  "code": "UNAUTHORIZED",
  "message": "Missing API key. Include x-api-key header in your request.",
  "status": 401
}

Solution: Add the x-api-key header to your request.

Invalid API Key

If your API key is invalid or malformed:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key",
  "status": 401
}

Solution: Verify your API key is correct and hasn't been deleted.

Expired API Key

If your API key has been revoked or deleted:

{
  "code": "UNAUTHORIZED",
  "message": "API key has been revoked",
  "status": 401
}

Solution: Generate a new API key from your workspace settings.

Insufficient Permissions

If your API key doesn't have permission to access a resource:

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions to access this resource",
  "status": 403
}

Solution: Verify your workspace has access to the requested feature. Contact support if needed.

Key Management

Workspace Scope

API keys are scoped to a specific workspace. Each key can only access resources within that workspace.

Team Access

All team members with workspace admin permissions can:

• View existing API keys (names only, not the actual keys)

• Generate new API keys

• Delete existing API keys

Key Deletion

Deleting an API key immediately revokes access. Any requests using that key will fail with a 401 Unauthorized error.

Deleting an API key cannot be undone. Ensure no active integrations are using the key before deletion.