Get started with Limitly in just a few minutes. This guide will walk you through setting up rate limiting for your application.

​
Prerequisites

  • Node.js 16+
  • A Limitly account (sign up at app.limitly.dev)
  • Your Limitly API key

​
Step 1: Install the SDK

npm install @limitly/limitly-js

​
Step 2: Initialize the SDK

import { Limitly } from '@limitly/limitly-js';

const limitly = new Limitly({
  apiKey: 'lk_1234567890abcdef1234567890abcdef'
});

​
Step 3: Create a Plan

First, create a usage plan for your users: 
const plan = await limitly.plans.create({
  name: 'Basic Plan',
  description: 'Plan for basic users',
  max_requests: 10000,
  request_period: 'month',
  features: ['api_access', 'basic_analytics']
});

console.log('Created plan:', plan.data?.id);

​
Step 4: Create a User

Create a user account: 
const user = await limitly.users.create({
  name: 'John Doe',
  email: 'john@example.com',
  plan_id: plan.data?.id
});

console.log('Created user:', user.data?.user_id);

​
Step 5: Generate an API Key

Create an API key for the user: 
const apiKey = await limitly.apiKeys.create({
  name: 'Production API Key',
  user_id: user.data?.user_id,
  plan_id: plan.data?.id
});

console.log('API Key:', apiKey.data?.api_key);

​
Step 6: Validate Requests

Now you can validate requests in your application: 
// In your API middleware
app.use(async (req, res, next) => {
  const userApiKey = req.headers['x-api-key'];
  
  if (!userApiKey) {
    return res.status(401).json({ error: 'API key required' });
  }
  
  const result = await limitly.validation.validate(
    userApiKey,
    req.path,
    req.method
  );
  
  if (!result.success) {
    return res.status(429).json({ 
      error: result.error,
      details: result.details 
    });
  }
  
  // Add usage info to response headers
  res.set('X-RateLimit-Limit', result.details?.limit?.toString());
  res.set('X-RateLimit-Remaining', result.details?.remaining?.toString());
  res.set('X-RateLimit-Reset', result.details?.reset_time);
  
  next();
});

​
Step 7: Test Your Integration

Test your rate limiting with a simple request: 
curl -H "X-API-Key: YOUR_USER_API_KEY" \
     http://localhost:3000/api/test
You should see the rate limit headers in the response: 
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9999
X-RateLimit-Reset: 2024-02-01T00:00:00Z

​
Complete Example

Here’s a complete Express.js example: 
import express from 'express';
import { Limitly } from '@limitly/limitly-js';

const app = express();
const limitly = new Limitly({
  apiKey: process.env.LIMITLY_API_KEY!
});

// Rate limiting middleware
app.use(async (req, res, next) => {
  const userApiKey = req.headers['x-api-key'] as string;
  
  if (!userApiKey) {
    return res.status(401).json({ error: 'API key required' });
  }
  
  try {
    const result = await limitly.validation.validate(
      userApiKey,
      req.path,
      req.method
    );
    
    if (!result.success) {
      return res.status(429).json({ 
        error: result.error,
        details: result.details 
      });
    }
    
    // Add usage info to response headers
    res.set('X-RateLimit-Limit', result.details?.limit?.toString());
    res.set('X-RateLimit-Remaining', result.details?.remaining?.toString());
    res.set('X-RateLimit-Reset', result.details?.reset_time);
    
    next();
  } catch (error) {
    console.error('Validation error:', error);
    return res.status(500).json({ error: 'Internal server error' });
  }
});

// Your API routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  res.json({ message: 'User created' });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

​
Next Steps