Cencori logo

Authentication

Learn how to authenticate your requests to the Cencori API using API keys and understand best practices for secure credential management.

API Key Authentication

Cencori uses API keys to authenticate requests. Your API key identifies your project and determines which security policies and rate limits apply to your requests.

Getting Your API Key

  1. Log in to the Cencori dashboard
  2. Navigate to your project
  3. Go to the "API Keys" tab
  4. Click "Generate New Key"
  5. Copy the key immediately (it won't be shown again)

Security Note: API keys are sensitive credentials. Never commit them to version control or expose them in client-side code.

Using API Keys

Include your API key when initializing the Cencori SDK. The SDK automatically adds the necessary authentication headers to all requests.

SDK Initialization

lib/cencori.ts

Direct HTTP Requests

If you're making direct HTTP requests without the SDK, include your API key in the Authorization header:

example-request.ts

Environment Variables

Store your API keys in environment variables to keep them secure and separate from your codebase.

Local Development

.env

Make sure to add .env to your .gitignore file.

Production Deployment

Set environment variables in your hosting platform:

  • Vercel: Project Settings → Environment Variables
  • Netlify: Site Settings → Build & Deploy → Environment
  • AWS/Docker: Use secrets management services (AWS Secrets Manager, Docker Secrets)
  • Heroku: Config Vars in the Settings tab

Required Headers

When making direct API requests, include these headers:

  • Authorization: Bearer YOUR_API_KEY (required)
  • X-Project-ID: Your project ID (required)
  • Content-Type: application/json (required for POST requests)
  • X-Environment: production or test (optional, defaults to production)
headers-example.ts

Authentication Errors

Handle authentication errors gracefully in your application.

Common Error Codes

error-examples.ts

Handling Errors

error-handling.ts

Security Best Practices

Follow these guidelines to keep your API keys secure:

  • Never expose keys in client-side code: API keys should only be used in server-side code or secure environments
  • Use environment variables: Store keys in .env files and never commit them to version control
  • Rotate keys regularly: Generate new keys periodically and revoke old ones
  • Use test keys for development: Keep production and test environments separate
  • Monitor API key usage: Check the dashboard for unusual activity or unauthorized access
  • Revoke compromised keys immediately: If a key is exposed, revoke it in the dashboard right away
  • Use separate keys for different services: Don't use the same key across multiple applications
  • Limit key permissions: Use keys with the minimum required permissions for each use case

API Key Rotation

Regularly rotating your API keys is a security best practice. Here's how to do it without downtime:

  1. Generate a new API key in the Cencori dashboard
  2. Update your application's environment variables with the new key
  3. Deploy the updated application
  4. Monitor logs to ensure the new key is working correctly
  5. Wait 24-48 hours to ensure all services are using the new key
  6. Revoke the old API key in the dashboard

Pro Tip: Set a calendar reminder to rotate your production keys every 90 days.

Testing Authentication

Verify your authentication setup with a simple test request:

test-auth.ts