Skip to main content
The Feather API uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure and never share them in publicly accessible areas.

​
Getting Your API Key

  1. Log in to your Feather Dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy your API key and store it securely
API keys are only shown once during creation. Make sure to copy and store your key in a secure location immediately.

​
API Key Header

Include your API key in the X-API-Key header: 
const API_KEY = process.env.FEATHER_API_KEY;

const response = await fetch('https://prod.featherhq.com/api/v1/agents', {
  headers: {
    'X-API-Key': `${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

​
Security Best Practices

​
Key Management Service (KMS)

For production environments, the most secure approach is to store API keys in a Key Management Service (KMS). KMS solutions provide:
  • Encryption at rest - Keys are encrypted when stored
  • Access control - Fine-grained permissions for who can access keys
  • Audit logging - Track all key access and usage
  • Automatic rotation - Scheduled key rotation without code changes
  • Secrets versioning - Maintain multiple versions of keys

​
AWS Secrets Manager

import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: "us-east-1" });

async function getFeatherApiKey() {
  const command = new GetSecretValueCommand({
    SecretId: "feather/api-key"
  });

  const response = await client.send(command);
  return response.SecretString;
}

// Use in your application
const FEATHER_API_KEY = await getFeatherApiKey();

const response = await fetch('https://prod.featherhq.com/api/v1/agents', {
  headers: {
    'X-API-Key': FEATHER_API_KEY,
    'Content-Type': 'application/json'
  }
});

​
Google Cloud Secret Manager

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const client = new SecretManagerServiceClient();

async function getFeatherApiKey() {
  const name = 'projects/YOUR_PROJECT_ID/secrets/feather-api-key/versions/latest';

  const [version] = await client.accessSecretVersion({ name });
  return version.payload.data.toString();
}

// Use in your application
const FEATHER_API_KEY = await getFeatherApiKey();

​
Azure Key Vault

import { SecretClient } from "@azure/keyvault-secrets";
import { DefaultAzureCredential } from "@azure/identity";

const vaultName = "your-vault-name";
const url = `https://${vaultName}.vault.azure.net`;

const credential = new DefaultAzureCredential();
const client = new SecretClient(url, credential);

async function getFeatherApiKey() {
  const secret = await client.getSecret("feather-api-key");
  return secret.value;
}

// Use in your application
const FEATHER_API_KEY = await getFeatherApiKey();

​
HashiCorp Vault

import vault from 'node-vault';

const client = vault({
  endpoint: 'http://vault.example.com:8200',
  token: process.env.VAULT_TOKEN
});

async function getFeatherApiKey() {
  const result = await client.read('secret/data/feather');
  return result.data.data.api_key;
}

// Use in your application
const FEATHER_API_KEY = await getFeatherApiKey();
Benefits of KMS:
  • No API keys stored in code or configuration files
  • Centralized secret management across services
  • Automatic encryption and decryption
  • Integration with cloud IAM for access control
  • Audit trails for compliance requirements

​
Environment Variables

For development and testing, environment variables are acceptable: 
# .env file
FEATHER_API_KEY=your_api_key_here

​
Key Rotation

  • Rotate your API keys regularly (recommended: every 90 days)
  • Immediately rotate keys if they may have been compromised
  • Use separate keys for development and production environments

​
Access Control

  • Only give API keys to team members who need them
  • Use separate keys for different applications or services
  • Monitor API key usage in the dashboard

​
Rate Limits

Feather API has the following rate limits:
  • Standard Plan: 10 RPS
  • Enterprise: Custom limits available
When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Error Codes

Status CodeDescription
401Invalid or missing API key
403API key doesn’t have required permissions
429Rate limit exceeded

​
Next Steps