Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.judit.io/llms.txt

Use this file to discover all available pages before exploring further.

🤖 The Judit API DOES NOT use the Authorization: Bearer <token> standard. Authentication is performed exclusively by passing the key in a custom HTTP header named api-key. This applies to all endpoints and Base URLs of the Judit API.

​
1. How to Obtain Your API Key

Your API Key is the unique credential that links your requests to your account and contracted plan.
  1. Contact our commercial team via WhatsApp.
  2. Provide context: Explain your use case and expected request volume.
  3. Receive the Key: Your API Key will be sent securely to your registered email address.
⚠️ Security First: Treat your API Key as a plaintext password. Never expose it in public repositories (e.g., GitHub), front-end code (client browser), or mobile applications without obfuscation.

​
2. Authentication Standard (api-key Header)

In every request made to the Judit API, regardless of service or module (Queries, Tracking, etc.), you must include the api-key header.

​
Basic HTTP Request Example

GET /requests HTTP/1.1
Host: requests.production.judit.io
api-key: your_api_key_here
Content-Type: application/json

​
Practical Implementation Examples

Below, we show how to perform an authenticated request using the Asynchronous Queries Base URL (https://requests.production.judit.io), consuming the key from environment variables. 
import os
import requests

# Configure API Key
api_key = os.getenv('JUDIT_API_KEY')

# Default headers
headers = {
    'api-key': api_key,
    'Content-Type': 'application/json'
}

# Make the request
response = requests.get(
    'https://requests.production.judit.io/requests',
    headers=headers
)

​
3. Secure Management and Best Practices

To prevent leaking your credential, consolidate the management of your key by following these rules:

​
1. Use Environment Variables Exclusively

Never hardcode your API Key in the source code: 
# ❌ WRONG - Never do this
api_key = "sk_live_1234567890abcdef"

# ✅ CORRECT - Use environment variables
api_key = os.getenv('JUDIT_API_KEY')

​
2. Configure Environment Variables

Linux/macOS: 
# In the ~/.bashrc or ~/.zshrc file
export JUDIT_API_KEY="your-api-key-here"

# Or for the current session
export JUDIT_API_KEY="your-api-key-here"
Windows: 
# Command Prompt
set JUDIT_API_KEY=your-api-key-here

# PowerShell
$env:JUDIT_API_KEY="your-api-key-here"
Docker: 
# Dockerfile
ENV JUDIT_API_KEY=""

# docker-compose.yml
environment:
  - JUDIT_API_KEY=${JUDIT_API_KEY}

​
3. .env File (Development)

# .env
JUDIT_API_KEY=your-api-key-here
JUDIT_BASE_URL=https://requests.production.judit.io

# Python with python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('JUDIT_API_KEY')

​
4. Key Rotation

  • Monitor the use of your API Key regularly
  • Request a new key if you suspect it has been compromised
  • Implement rotation in critical environments

​
Authentication Error Handling

​
401 Error - Unauthorized

{
  "error": {
        "name": "HttpUnauthorizedError",
        "message": "UNAUTHORIZED",
        "data": "USER_NOT_FOUND"
    }
}
Possible causes:
  • API Key not provided
  • Invalid or expired API Key
  • Badly formatted api-key header
  • Usage limit exceeded

​
403 Error - Forbidden

{
  "error": "Forbidden",
  "message": "Acesso negado para este recurso",
  "code": "INSUFFICIENT_PERMISSIONS"
}
Possible causes:
  • Valid API Key but without permission for the resource
  • Resource not available in your plan

​
API Key Validation

​
Connectivity Test

import requests

def test_api_key(api_key):
    """Tests whether the API Key is valid"""
    headers = {'api-key': api_key}
    
    try:
        response = requests.get(
            'https://requests.production.judit.io/requests',
            headers=headers,
            params={'page': 1, 'page_size': 1}
        )
        
        if response.status_code == 200:
            print("✅ Valid API Key")
            return True
        elif response.status_code == 401:
            print("❌ Invalid API Key")
            return False
        else:
            print(f"⚠️ Unexpected error: {response.status_code}")
            return False
            
    except requests.RequestException as e:
        print(f"❌ Connection error: {e}")
        return False

# Use the function
api_key = os.getenv('JUDIT_API_KEY')
test_api_key(api_key)

​
Usage Monitoring

def check_api_usage(response):
    """
    Monitors API usage through the response headers.
    
    Note: The API has a strict rate limit of 180 requests per minute.
    This function calculates the percentage consumed in the current time window.
    """
    
    # Capture limit information from the headers (Expected: 180 per minute)
    limit = response.headers.get('X-RateLimit-Limit')
    remaining = response.headers.get('X-RateLimit-Remaining')
    reset = response.headers.get('X-RateLimit-Reset')
    
    if limit and remaining:
        # Calculate the usage percentage based on the returned limit
        usage_percent = ((int(limit) - int(remaining)) / int(limit)) * 100
        
        print(f"API limit: {limit} requests/minute")
        print(f"API usage: {usage_percent:.1f}%")
        print(f"Remaining requests this minute: {remaining}")
        
        # Alert if usage exceeds 80% (approx. 144 requests)
        if usage_percent > 80:
            print("⚠️ Warning: Close to the rate limit (180/min)!")

​
Environment-Based Configuration

# config/production.py
import os

API_KEY = os.getenv('JUDIT_API_KEY')
BASE_URL = 'https://requests.production.judit.io'
TIMEOUT = 10
RETRY_ATTEMPTS = 3

​
Configuration Class

class JuditConfig:
    def __init__(self, environment='production'):
        self.environment = environment
        self.api_key = self._get_api_key()
        self.base_url = 'https://requests.production.judit.io'
        
    def _get_api_key(self):
        key_name = f'JUDIT_API_KEY_{self.environment.upper()}'
        api_key = os.getenv(key_name)
        
        if not api_key:
            raise ValueError(f"API Key not found: {key_name}")
            
        return api_key
    
    @property
    def headers(self):
        return {
            'api-key': self.api_key,
            'Content-Type': 'application/json'
        }

# Usage
config = JuditConfig('production')
response = requests.get(f"{config.base_url}/requests", 
    headers=config.headers)

​
Next Steps

Support: If you have authentication problems, contact our technical support.