Skip to main content

​
Authentication

Raptor Data uses API keys to authenticate requests. All API requests must include a valid API key in the Authorization header.

​
Creating an API Key

  1. Sign in to your Raptor Data Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Production”, “Development”, “CI/CD”)
  5. Copy the API key immediately
The API key is only shown once during creation. Store it securely in a password manager or environment variable.

​
Using Your API Key

​
TypeScript SDK

import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY // Store in environment variable
});

​
REST API

Include your API key in the Authorization header: 
curl https://api.raptordata.dev/api/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

​
Environment Variables

Store your API key in environment variables to keep it secure:

​
Node.js / TypeScript

# .env file
RAPTOR_API_KEY=rd_live_abc123def456...

// Load from .env
import Raptor from '@raptor-data/ts-sdk';
import dotenv from 'dotenv';

dotenv.config();

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY
});

​
Next.js

# .env.local
RAPTOR_API_KEY=rd_live_abc123def456...
In Next.js, only use API keys in server-side code (API routes, getServerSideProps, Server Components). Never expose API keys in client-side code.
// app/api/process/route.ts (Next.js 13+ App Router)
import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY
});

export async function POST(request: Request) {
  const formData = await request.formData();
  const file = formData.get('file');

  const result = await raptor.process(file);
  return Response.json(result);
}

​
Browser-Based Apps

Never expose API keys in client-side JavaScript. Always proxy requests through your backend.
Recommended Architecture: 
Browser → Your Backend API → Raptor API
         (API key here)
Example with Next.js API route: 
// Client-side
const response = await fetch('/api/raptor/upload', {
  method: 'POST',
  body: formData
});

// Server-side (pages/api/raptor/upload.ts)
import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY // Secure server-side
});

export default async function handler(req, res) {
  const file = req.body;
  const result = await raptor.process(file);
  res.json(result);
}

​
API Key Management

​
Regenerating API Keys

If your API key is compromised:
  1. Go to Dashboard → Settings → API Keys
  2. Click Regenerate on the compromised key
  3. Update your application with the new key
  4. The old key is immediately deactivated

​
Multiple API Keys

Create multiple API keys for different environments:
  • Production: For your live application
  • Development: For local development
  • Staging: For staging environment
  • CI/CD: For automated testing pipelines

​
Deleting API Keys

To remove an API key:
  1. Go to Dashboard → Settings → API Keys
  2. Click Delete on the key you want to remove
  3. Confirm deletion
The key is immediately deactivated and cannot be used for new requests.

​
Rate Limits

Rate limits are enforced per API key and depend on your plan:
PlanRequests per MinuteConcurrent Processing
Free101
Basic1003
Plus50010
Premium2,00025
Business5,00050
EnterpriseCustomCustom

​
Handling Rate Limits

When you exceed rate limits, the API returns a 429 Too Many Requests status: 
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
SDK Automatic Retry: The SDK automatically handles rate limits with exponential backoff: 
const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY,
  timeout: 300000 // 5 minutes
});

// SDK will automatically retry on 429 errors
const result = await raptor.process(file);

​
Security Best Practices

Always use environment variables and add .env to your .gitignore:
# .gitignore
.env
.env.local
.env.*.local
Create separate API keys for development, staging, and production. This allows you to rotate keys without affecting other environments.
Periodically regenerate your API keys as a security best practice, especially for production environments.
Check the Last Used timestamp in your dashboard to detect unauthorized usage:
  • If a key shows recent activity but you haven’t used it, regenerate it immediately
  • Delete unused keys to reduce your attack surface
Never expose API keys in client-side JavaScript. Always proxy requests through your backend API.
Enterprise plans can restrict API keys to specific IP addresses or CIDR ranges.

​
Troubleshooting

​
401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
Solutions:
  • Verify your API key is correct and hasn’t been regenerated
  • Check that the Authorization header is formatted correctly: Bearer YOUR_KEY
  • Ensure the API key hasn’t been deleted

​
403 Forbidden

{
  "error": "insufficient_permissions",
  "message": "Your plan does not support this feature"
}
Solution: Upgrade your plan to access this feature.

​
429 Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded"
}
Solutions:
  • Wait for the rate limit window to reset (60 seconds)
  • Upgrade your plan for higher rate limits
  • Implement exponential backoff in your application

​
Next Steps

Quickstart

Start uploading documents with your API key

SDK Reference

Explore the TypeScript SDK