API Reference
Authentication

API Authentication

The NIL Taxonomy API uses Bearer token authentication with API keys.

Authentication Method

Include your API key in the Authorization header:

GET /api/nil/v1/licenses
Authorization: Bearer nilk_your_key_here

cURL Example

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

JavaScript/TypeScript

const response = await fetch('https://api.nil-taxonomy.org/api/nil/v1/licenses', {
  headers: {
    'Authorization': `Bearer ${process.env.NIL_TAXONOMY_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
 
const data = await response.json();

Using the SDK

The SDK handles authentication automatically:

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!,
});
 
// API key included automatically
const licenses = await client.getBaseLicenses('v1');

Getting an API Key

Request Access

Email licensing@nil-taxonomy.org with:

  • Organization name
  • Use case description
  • Expected usage volume
  • Deployment environment

Receive Your Key

You'll receive a key in format: nilk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🚫

Save this key immediately. You cannot retrieve it again.

Store Securely

Add to environment variables:

.env.local
NIL_TAXONOMY_API_KEY=nilk_your_key_here

Add to .gitignore:

.env.local
.env*.local

Test Connection

const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});
 
try {
  await client.getVersions();
  console.log('✓ Authentication successful');
} catch (error) {
  console.error('✗ Authentication failed:', error);
}

Authentication Errors

401 Unauthorized - Missing Key

{
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

Solution: Include Authorization: Bearer <key> header

401 Unauthorized - Invalid Key

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solutions:

  • Verify key is correct (check for typos/spaces)
  • Check key hasn't been revoked
  • Ensure key status is 'active'

403 Forbidden - Revoked Key

{
  "error": "Forbidden",
  "message": "API key has been revoked"
}

Solution: Contact support to generate a new key

Security Best Practices

1. Never Expose Keys Client-Side

// ❌ BAD: Client-side exposure
const App = () => {
  const apiKey = 'nilk_hardcoded_key'; // Visible in browser!
  // ...
};
 
// ✅ GOOD: Server-side only
export async function GET(request: Request) {
  const apiKey = process.env.NIL_TAXONOMY_API_KEY; // Server-side
  // ...
}

2. Use Environment Variables

# .env.local (add to .gitignore)
NIL_TAXONOMY_API_KEY=nilk_xxxxx
const apiKey = process.env.NIL_TAXONOMY_API_KEY;

3. Separate Keys Per Environment

  • Development - Local testing
  • Staging - Pre-production testing
  • Production - Live deployment

4. Rotate Keys Regularly

Rotate keys every 90 days:

  1. Generate new key
  2. Update environment variables
  3. Deploy with new key
  4. Verify it works
  5. Revoke old key

5. Monitor Usage

Check key usage regularly for unusual activity:

// Future: API endpoint for usage stats
const stats = await client.getKeyUsage();
console.log('Requests this month:', stats.count);

Key Management

Revoking Keys

If a key is compromised:

  1. Email security@nil-taxonomy.org
  2. Include key prefix (first 12 chars: nilk_abc123...)
  3. Receive replacement key

Multiple Keys

You can have multiple active keys:

// Different keys for different services
const internalClient = new NILTaxonomyClient({
  apiKey: process.env.INTERNAL_API_KEY // For internal tools
});
 
const publicClient = new NILTaxonomyClient({
  apiKey: process.env.PUBLIC_API_KEY // For public-facing app
});

Next Steps

EndpointsError Codes