Authentication

Access to the NIL Taxonomy API requires authentication with an API key.

Getting an API Key

nilk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

NIL_TAXONOMY_API_KEY=nilk_your_key_here
NIL_TAXONOMY_API_URL=https://api.nil-taxonomy.org/api/nil

import { NILTaxonomyClient } from '@nil-taxonomy/sdk';
 
const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});
 
try {
  const versions = await client.getVersions();
  console.log('✓ Connected successfully');
  console.log('Available versions:', versions);
} catch (error) {
  console.error('✗ Connection failed:', error);
}

SDK Configuration

Basic Setup

import { NILTaxonomyClient } from '@nil-taxonomy/sdk';
 
const client = new NILTaxonomyClient({
  baseUrl: 'https://api.nil-taxonomy.org/api/nil',
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});

Advanced Configuration

const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
  timeout: 30000,        // Request timeout in ms (default: 30000)
  retries: 3,            // Number of retries on failure (default: 3)
  retryDelay: 1000,      // Delay between retries in ms (default: 1000)
});

API Key Usage

In API Requests

When making direct HTTP requests (without the SDK), include your API key in the Authorization header:

curl -H "Authorization: Bearer nilk_your_key_here" \
  https://api.nil-taxonomy.org/api/nil/v1/licenses

Key Management

Rotate Keys

For security, rotate your API keys periodically:

1. Generate a new key
2. Update your environment variables
3. Deploy the update
4. Revoke the old key after confirming the new one works

Revoke Compromised Keys

If your key is compromised:

1. Email security@nil-taxonomy.org immediately
2. Include the key prefix (first 12 characters)
3. We'll revoke it and issue a replacement

Rate Limits

API keys have usage quotas based on tier:

Rate limit information is returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Troubleshooting

"Invalid API Key" Error

• Verify the key is correct (no extra spaces)
• Check that the key hasn't been revoked
• Ensure you're using Bearer authentication scheme

Rate Limit Exceeded

• Upgrade to a higher tier
• Implement caching to reduce API calls
• Contact support for temporary limit increases

Connection Timeout

• Check your network connectivity
• Verify firewall settings allow HTTPS traffic
• Try increasing the timeout value in client config

Security Best Practices

1. Never commit keys to version control

   • Use .env files (add to .gitignore)
   • Use environment variables in production

2. Use separate keys for environments

   • Development key for local testing
   • Staging key for pre-production
   • Production key for live deployments

3. Monitor key usage

   • Check usage stats regularly
   • Set up alerts for unusual activity
   • Rotate keys every 90 days

4. Restrict key access

   • Only share keys with authorized team members
   • Use secrets management (AWS Secrets Manager, Vault, etc.)
   • Revoke keys when team members leave

Next Steps

• Build your first license →
• Explore the SDK →
• View API endpoints →