Authentication on the Judit API

🤖 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.

Contact our commercial team via WhatsApp.
Provide context: Explain your use case and expected request volume.
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
)

// Configure API Key
const apiKey = process.env.JUDIT_API_KEY;

// Default headers
const headers = {
    'api-key': apiKey,
    'Content-Type': 'application/json'
};

// Make the request
const response = await fetch('https://requests.production.judit.io/requests', {
    method: 'GET',
    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

Rate Limits: Understand the usage limits
Pagination: Configure paginated queries
Endpoints: Explore the available resources

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

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

1. How to Obtain Your API Key

2. Authentication Standard (`api-key` Header)

Basic HTTP Request Example

Practical Implementation Examples

3. Secure Management and Best Practices

1. Use Environment Variables Exclusively

2. Configure Environment Variables

3. .env File (Development)

4. Key Rotation

Authentication Error Handling

401 Error - Unauthorized

403 Error - Forbidden

API Key Validation

Connectivity Test

Usage Monitoring

Environment-Based Configuration

Configuration Class

Next Steps

​1. How to Obtain Your API Key

​2. Authentication Standard (api-key Header)

​Basic HTTP Request Example

​Practical Implementation Examples

​3. Secure Management and Best Practices

​1. Use Environment Variables Exclusively

​2. Configure Environment Variables

​3. .env File (Development)

​4. Key Rotation

​Authentication Error Handling

​401 Error - Unauthorized

​403 Error - Forbidden

​API Key Validation

​Connectivity Test

​Usage Monitoring

​Environment-Based Configuration

​Configuration Class

​Next Steps

1. How to Obtain Your API Key

2. Authentication Standard (`api-key` Header)

Basic HTTP Request Example

Practical Implementation Examples

3. Secure Management and Best Practices

1. Use Environment Variables Exclusively

2. Configure Environment Variables

3. .env File (Development)

4. Key Rotation

Authentication Error Handling

401 Error - Unauthorized

403 Error - Forbidden

API Key Validation

Connectivity Test

Usage Monitoring

Environment-Based Configuration

Configuration Class

Next Steps