Quick Start

Get started with LightRate in minutes. This guide will walk you through setting up your account, creating your first rate limiting rule, and integrating with your application.

Create Your Account and Get API Credentials

Sign up for a LightRate account at https://lightrate.lightbournetechnologies.ca
Navigate to Settings → API Keys
Click Create API Key
Save your API key securely - you’ll need it for configuration

Keep your API key secure! Never commit it to version control. Use environment variables instead.

Create Your First Application

Applications are containers for rate limiting rules.

Go to Dashboard → Applications
Click Create Application
Enter your application details:
- Name: e.g., “My API”
- Default Refill Rate: 5 tokens/second (how fast tokens replenish)
- Default Burst Rate: 50 tokens (maximum tokens available)
Copy your Application ID - you’ll need this for your client configuration

Install the Client SDK

Choose your language/framework and install the appropriate SDK:

Ruby

Add to your Gemfile:


gem 'lightrate-client'

Then install:


bundle install

Rails

Add to your Gemfile:


gem 'lightrate-rails'

Then install:


bundle install

JavaScript

Install with npm:


npm install lightrate-client

Or with yarn:


yarn add lightrate-client

Express

Install with npm:


npm install lightrate-client-express

Or with yarn:


yarn add lightrate-client-express

Python

Install with pip:


pip install lightrate-client

Or with pipenv:


pipenv install lightrate-client

C#

Install via NuGet Package Manager:


Install-Package LightRateClient

Or via .NET CLI:


dotnet add package LightRateClient

Or add to your .csproj:


<PackageReference Include="LightRateClient" Version="1.0.0" />

Java

Add to your pom.xml:


<dependency>
    <groupId>ca.lightbournetechnologies</groupId>
    <artifactId>lightrate-client</artifactId>
    <version>1.0.0</version>
</dependency>

Or if using Gradle, add to build.gradle:


dependencies {
    implementation 'ca.lightbournetechnologies:lightrate-client:1.0.0'
}

Configure Your Client

Set up your client with the API key and Application ID from steps 1 and 2:

Ruby


require 'lightrate_client'
 
# Configure globally
LightrateClient.configure do |config|
  config.api_key = ENV['LIGHTRATE_API_KEY']
  config.application_id = ENV['LIGHTRATE_APPLICATION_ID']
end
 
# Or create a client instance
client = LightrateClient::Client.new(
  ENV['LIGHTRATE_API_KEY'],
  ENV['LIGHTRATE_APPLICATION_ID']
)

Rails

Create an initializer:


# config/initializers/lightrate_rails.rb
 
LightrateRails.configure do |config|
  config.api_key = ENV['LIGHTRATE_API_KEY']
  config.application_id = ENV['LIGHTRATE_APPLICATION_ID']
  config.enabled = Rails.env.production?
end

JavaScript


const { LightRateClient } = require('lightrate-client');
 
// Create a client instance
const client = new LightRateClient(
  process.env.LIGHTRATE_API_KEY,
  {
    applicationId: process.env.LIGHTRATE_APPLICATION_ID
  }
);

Or configure globally:


const { configure, getClient } = require('lightrate-client');
 
configure({
  apiKey: process.env.LIGHTRATE_API_KEY,
  applicationId: process.env.LIGHTRATE_APPLICATION_ID
});
 
const client = getClient();

Express


const express = require('express');
const { configure, lightrateMiddleware } = require('lightrate-client-express');
 
const app = express();
 
// Configure once at startup
configure({
  apiKey: process.env.LIGHTRATE_API_KEY,
  applicationId: process.env.LIGHTRATE_APPLICATION_ID
});

Python


from lightrate_client import LightRateClient
import os
 
# Create a client instance
client = LightRateClient(
    os.environ['LIGHTRATE_API_KEY'],
    os.environ['LIGHTRATE_APPLICATION_ID']
)

C#


using LightRateClient.Client;
 
// Create a client instance
var client = new LightRateClient(
    Environment.GetEnvironmentVariable("LIGHTRATE_API_KEY"),
    Environment.GetEnvironmentVariable("LIGHTRATE_APPLICATION_ID")
);

Java


import ca.lightbournetechnologies.lightrate.client.LightRateClient;
 
// Create a client instance
LightRateClient client = new LightRateClient(
    System.getenv("LIGHTRATE_API_KEY"),
    System.getenv("LIGHTRATE_APPLICATION_ID")
);

Add Rate Limiting to Your Code

Now implement rate limiting in your application:

Ruby


# Consume tokens for an operation (uses local token bucket)
response = client.consume_local_bucket_token(
  operation: 'send_email',
  user_identifier: 'user123'
)
 
if response.success
  # Proceed with your operation
  send_email_to_user(user)
  puts "Email sent! Token consumed from #{response.used_local_token ? 'local bucket' : 'server'}"
else
  # Rate limited
  puts "Rate limit exceeded. Please try again later."
end

Rails

Add to your controller:


class ApiController < ApplicationController
  # Automatically throttle all actions
  throttle_with_lightrate
  
  def send_email
    # Your code here - automatically rate limited!
    UserMailer.notification_email(@user).deliver_now
    render json: { message: 'Email sent' }
  end
end

Or throttle specific actions:


class UsersController < ApplicationController
  # Only throttle write operations
  throttle_with_lightrate only: [:create, :update, :destroy]
  
  def create
    # Rate limited
    @user = User.create(user_params)
    render json: @user
  end
end

JavaScript


// Consume tokens for an operation (uses local token bucket)
const response = await client.consumeLocalBucketToken(
  'user123',      // userIdentifier
  'send_email'    // operation
);
 
if (response.success) {
  // Proceed with your operation
  await sendEmailToUser(user);
  console.log(`Email sent! Token consumed from ${response.usedLocalToken ? 'local bucket' : 'server'}`);
} else {
  // Rate limited
  console.log('Rate limit exceeded. Please try again later.');
}

Express


// Create middleware
const rateLimiter = lightrateMiddleware({
  getUserIdentifier: (req) => req.user?.id
});
 
// Apply to all routes
app.use(rateLimiter);
 
// Your routes are now automatically rate limited
app.post('/api/send-email', async (req, res) => {
  await sendEmailToUser(req.user);
  res.json({ message: 'Email sent' });
});
 
app.listen(3000);

Or apply to specific routes:


// Rate limit only specific endpoints
app.post('/api/send-email', rateLimiter, async (req, res) => {
  await sendEmailToUser(req.user);
  res.json({ message: 'Email sent' });
});

Python


# Consume tokens for an operation (uses local token bucket)
response = client.consume_local_bucket_token(
    user_identifier='user123',
    operation='send_email'
)
 
if response.success:
    # Proceed with your operation
    send_email_to_user(user)
    print(f"Email sent! Token consumed from {'local bucket' if response.used_local_token else 'server'}")
else:
    # Rate limited
    print("Rate limit exceeded. Please try again later.")

C#


// Consume tokens for an operation (uses local token bucket)
var response = client.ConsumeLocalBucketToken(
    userIdentifier: "user123",
    operation: "send_email"
);
 
if (response.Success)
{
    // Proceed with your operation
    SendEmailToUser(user);
    Console.WriteLine($"Email sent! Token consumed from {(response.UsedLocalToken ? "local bucket" : "server")}");
}
else
{
    // Rate limited
    Console.WriteLine("Rate limit exceeded. Please try again later.");
}

Java


// Consume tokens for an operation (uses local token bucket)
ConsumeLocalBucketTokenResponse response = client.consumeLocalBucketToken(
    "user123",      // userIdentifier
    "send_email"    // operation
);
 
if (response.isSuccess()) {
    // Proceed with your operation
    sendEmailToUser(user);
    String source = response.isUsedLocalToken() ? "local bucket" : "server";
    System.out.println("Email sent! Token consumed from " + source);
} else {
    // Rate limited
    System.out.println("Rate limit exceeded. Please try again later.");
}

What’s Next?

Now that you have basic rate limiting set up, explore more advanced features:

Custom User Identification - Rate limit by API key, IP address, or custom identifiers
Multiple Rate Limits - Create different rules for different operations
Error Handling - Handle rate limit errors gracefully
Local Token Buckets - Understand how LightRate improves performance with client-side buckets

Need Help?

Full Documentation - Complete API reference and guides
SDK Documentation - Detailed docs for each client library
Support - Contact us at support@lightbourne.com

Common Issues

Rate limits not working? Make sure you:

Have the correct API key and Application ID
Created at least one rule or are using the default application limits
Are using the correct user identifier format
Have internet connectivity (client needs to reach LightRate API)