# API Armor — Full Documentation

> API protection and anti-fraud platform: disposable-email and IP-reputation checks plus device fingerprinting.

This file contains the full API Armor documentation as Markdown, concatenated for LLM consumption. It covers two products: Bifrost, a REST API (bifrost.api-armor.com) for disposable/temporary email detection and IP reputation checks called from your backend, and Argus, an embeddable browser SDK that returns a stable device fingerprint (argus_visitor_id) from a single script tag. The link index is at https://api-armor.com/llms.txt, and any single page is available by appending ".md" to its URL.

# Introduction
URL: https://api-armor.com/docs

> Protect your application from fraud and abuse. Bifrost validates emails and IP reputation via REST API; Argus fingerprints devices with an embeddable browser SDK.

- [Simple REST API](/docs/quick-start): Easy-to-integrate REST API with a single endpoint

- [99.9% Uptime](/docs/api-reference): Reliable service with guaranteed uptime

- [Free Tier](/pricing): Free tier available for developers

- [Real-time Updates](/docs/api-reference): Domain database updated in real-time

## Two products, one platform [#two-products-one-platform]

**Bifrost** is a REST API for disposable-email and IP-reputation checks you call from your backend. **Argus** is an embeddable device-fingerprinting SDK you add to your website with a single `<script>` tag — no backend calls required.

- [Argus: Device Fingerprinting](/docs/argus): Identify and re-recognize devices with a privacy-respecting browser SDK. Requires a Developer or Pro plan.

- [Argus Quick Start](/docs/argus/quick-start): Add one script tag and start identifying visitors in five minutes.

## Quick Examples [#quick-examples]

Get started in seconds with simple API calls:

### Check Email [#check-email]

```bash
curl "https://bifrost.api-armor.com/v1/check?email=layohe8924@badfist.com" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const response = await fetch(
  'https://bifrost.api-armor.com/v1/check?email=layohe8924@badfist.com',
  {
    headers: {
      'Authorization': 'Bearer aa_abc123xyz789'
    }
  }
);
const data = await response.json();
console.log(data);
```

```python
import requests

response = requests.get(
    'https://bifrost.api-armor.com/v1/check',
    params={'email': 'layohe8924@badfist.com'},
    headers={'Authorization': 'Bearer aa_abc123xyz789'}
)
data = response.json()
print(data)
```

**Response:**

```json
{
  "email": "layohe8924@badfist.com",
  "is_disposable": true,
  "domain": "badfist.com",
  "free_email": false
}
```

### Check IP Intelligence [#check-ip-intelligence]

```bash
curl "https://bifrost.api-armor.com/v1/ip-reputation-check?ip=159.89.165.46" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const response = await fetch(
  'https://bifrost.api-armor.com/v1/ip-reputation-check?ip=159.89.165.46',
  {
    headers: {
      'Authorization': 'Bearer aa_abc123xyz789'
    }
  }
);
const data = await response.json();
console.log(data);
```

```python
import requests

response = requests.get(
    'https://bifrost.api-armor.com/v1/ip-reputation-check',
    params={'ip': '159.89.165.46'},
    headers={'Authorization': 'Bearer aa_abc123xyz789'}
)
data = response.json()
print(data)
```

**Response:**

```json
{
  "ip": "159.89.165.46",
  "country": "United States",
  "city": "Santa Clara",
  "isp": "DigitalOcean, LLC",
  "reputation": {
    "risky": true,
    "reputation": "suspicious",
    "sum": 28,
    "kind": ["hosting"]
  }
}
```

> **Get Your Free API Key**
>
> Ready to get started? [Sign up for a free API key](/signup) and start protecting your application today.

## Key Features [#key-features]

### Email Validation [#email-validation]

Detect disposable, temporary, and throwaway email addresses with our constantly updated database. Catch fake signups before they start.

### IP Intelligence [#ip-intelligence]

Real-time IP threat scoring with detailed geolocation, ISP information, and network classification. Identify VPNs, proxies, hosting providers, and malicious traffic.

### Lightning Fast [#lightning-fast]

Average response time under 100ms globally with Redis-backed caching. Our API is optimized for speed without compromising accuracy.

### Easy Integration [#easy-integration]

Simple REST API with clear JSON responses. Integrate in minutes, not hours. SDKs available for all major languages.

## Next Steps [#next-steps]

- [Quick Start Guide](/docs/quick-start): Get up and running in 5 minutes

- [Authentication](/docs/authentication): Learn how to authenticate your requests

- [API Reference](/docs/api-reference): Explore the complete API documentation

- [Error Handling](/docs/errors): Handle errors gracefully in your application


---

# Quick Start Guide
URL: https://api-armor.com/docs/quick-start

> Get started with API Armor in minutes. Follow this step-by-step guide to integrate email validation and IP intelligence into your application.

## Getting Started [#getting-started]

This guide will walk you through integrating API Armor into your application in just a few minutes. You'll learn how to check disposable emails and get IP intelligence.

## Step 1: Get Your API Key [#step-1-get-your-api-key]

First, you'll need an API key to authenticate your requests.

1. [Sign up for a free account](/signup)
2. Navigate to your [dashboard](/dashboard)
3. Generate a new API key
4. Copy and securely store your API key

> **Keep Your API Key Secret**
>
> Never expose your API key in client-side code or commit it to version control. Use environment variables to store your key securely.

## Step 2: Make Your First Request [#step-2-make-your-first-request]

Let's make a simple request to check if an email is disposable:

```bash
curl "https://bifrost.api-armor.com/v1/check?email=test@example.com" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const API_KEY = process.env.API_SHIELD_KEY;

async function checkEmail(email) {
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
const result = await checkEmail('layohe8924@badfist.com');
console.log(result);
```

```python
import os
import requests

API_KEY = os.environ.get('API_SHIELD_KEY')

def check_email(email):
    response = requests.get(
        'https://bifrost.api-armor.com/v1/check',
        params={'email': email},
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = check_email('layohe8924@badfist.com')
print(result)
```

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
)

type EmailCheckResponse struct {
    Email        string `json:"email"`
    IsDisposable bool   `json:"is_disposable"`
    Domain       string `json:"domain"`
    FreeEmail    bool   `json:"free_email"`
}

func checkEmail(email string) (*EmailCheckResponse, error) {
    apiKey := os.Getenv("API_SHIELD_KEY")
    baseURL := "https://bifrost.api-armor.com/v1/check"
    
    params := url.Values{}
    params.Add("email", email)
    
    req, err := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    if err != nil {
        return nil, err
    }
    
    req.Header.Set("Authorization", "Bearer "+apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var result EmailCheckResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    
    return &result, nil
}

func main() {
    result, err := checkEmail("layohe8924@badfist.com")
    if err != nil {
        panic(err)
    }
    fmt.Printf("%+v\n", result)
}
```

```php
<?php

$apiKey = getenv('API_SHIELD_KEY');

function checkEmail($email) {
    global $apiKey;
    
    $url = 'https://bifrost.api-armor.com/v1/check?' . http_build_query([
        'email' => $email
    ]);
    
    $options = [
        'http' => [
            'method' => 'GET',
            'header' => "Authorization: Bearer $apiKey\r\n"
        ]
    ];
    
    $context = stream_context_create($options);
    $response = file_get_contents($url, false, $context);
    
    return json_decode($response, true);
}

// Usage
$result = checkEmail('layohe8924@badfist.com');
print_r($result);
```

## Step 3: Handle the Response [#step-3-handle-the-response]

The API returns a simple JSON response:

```json
{
  "email": "layohe8924@badfist.com",
  "is_disposable": true,
  "domain": "badfist.com",
  "free_email": false
}
```

### Response Fields [#response-fields]

| Field           | Type    | Description                                                                                          |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `email`         | string  | The email address that was checked                                                                   |
| `is_disposable` | boolean | `true` if the email is from a disposable domain, `false` otherwise                                   |
| `domain`        | string  | The domain extracted from the email address                                                          |
| `free_email`    | boolean | `true` if the domain is a known free email provider (e.g., Gmail, Yahoo, Outlook), `false` otherwise |

## Step 4: Integrate Into Your Application [#step-4-integrate-into-your-application]

Here's a complete example of integrating API Shield into a signup form:

```javascript
import { useState } from 'react';

function SignupForm() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');
  const [loading, setLoading] = useState(false);

  const validateEmail = async (email) => {
    try {
      const response = await fetch(
        `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.NEXT_PUBLIC_API_SHIELD_KEY}`
          }
        }
      );
      
      const data = await response.json();
      
      if (data.is_disposable) {
        setError('Please use a valid email address. Disposable emails are not allowed.');
        return false;
      }
      
      return true;
    } catch (err) {
      console.error('Email validation error:', err);
      return true; // Fail open - don't block signup on API errors
    }
  };

  const handleSubmit = async (e) => {
    e.preventDefault();
    setError('');
    setLoading(true);

    const isValid = await validateEmail(email);
    
    if (isValid) {
      // Proceed with signup
      console.log('Email is valid, proceeding with signup...');
    }
    
    setLoading(false);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter your email"
        required
      />
      {error && <p className="error">{error}</p>}
      <button type="submit" disabled={loading}>
        {loading ? 'Validating...' : 'Sign Up'}
      </button>
    </form>
  );
}
```

```python
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
API_KEY = os.environ.get('API_SHIELD_KEY')

def check_disposable_email(email):
    try:
        response = requests.get(
            'https://bifrost.api-armor.com/v1/check',
            params={'email': email},
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=5
        )
        response.raise_for_status()
        data = response.json()
        return data.get('is_disposable', False)
    except Exception as e:
        print(f"Email check error: {e}")
        return False  # Fail open

@app.route('/signup', methods=['POST'])
def signup():
    data = request.get_json()
    email = data.get('email')
    
    if not email:
        return jsonify({'error': 'Email is required'}), 400
    
    # Check if email is disposable
    if check_disposable_email(email):
        return jsonify({
            'error': 'Disposable emails are not allowed'
        }), 400
    
    # Proceed with signup
    # ... your signup logic here
    
    return jsonify({'message': 'Signup successful'}), 201
```

> **Best Practice: Fail Open**
>
> If the API is unreachable or returns an error, it's recommended to "fail open" - allow the signup to proceed rather than blocking legitimate users. You can log these cases for later review.

## Step 5: Test Your Integration [#step-5-test-your-integration]

Test with known disposable email providers:

* ✅ Valid: `user@gmail.com`, `user@outlook.com`, `user@company.com`
* ❌ Disposable: `layohe8924@badfist.com`, `user@tempmail.com`, `test@guerrillamail.com`

## IP Intelligence [#ip-intelligence]

In addition to email validation, you can also get IP intelligence to protect against malicious traffic, VPNs, and hosting providers.

### Basic IP Intelligence Check [#basic-ip-intelligence-check]

```bash
curl "https://bifrost.api-armor.com/v1/ip-reputation-check?ip=159.89.165.46" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const API_KEY = process.env.API_ARMOR_KEY;

async function checkIPIntelligence(ip) {
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${encodeURIComponent(ip)}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  
  return await response.json();
}

// Usage
const result = await checkIPIntelligence('159.89.165.46');
console.log(result);
```

```python
import os
import requests

API_KEY = os.environ.get('API_ARMOR_KEY')

def check_ip_intelligence(ip):
    response = requests.get(
        'https://bifrost.api-armor.com/v1/ip-reputation-check',
        params={'ip': ip},
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    response.raise_for_status()
    return response.json()

# Usage
result = check_ip_intelligence('159.89.165.46')
print(result)
```

### Response [#response]

The IP intelligence endpoint returns comprehensive data:

```json
{
  "ip": "159.89.165.46",
  "country": "United States",
  "city": "Santa Clara",
  "isp": "DigitalOcean, LLC",
  "latitude": 37.3986,
  "longitude": -121.964,
  "timezone": "America/Los_Angeles",
  "reputation": {
    "risky": true,
    "reputation": "suspicious",
    "bot": 1,
    "probe": 27,
    "attack": 0,
    "sum": 28,
    "kind": ["hosting"]
  }
}
```

### Integration Example [#integration-example]

```javascript
app.post('/api/signup', async (req, res) => {
  const clientIP = req.headers['x-forwarded-for']?.split(',')[0] || 
                   req.socket.remoteAddress;

  try {
    const ipData = await checkIPIntelligence(clientIP);
    
    // Block risky IPs
    if (ipData.reputation.risky) {
      return res.status(403).json({
        error: 'Suspicious IP address detected'
      });
    }
    
    // Flag VPN/hosting users for review
    if (ipData.reputation.kind.includes('hosting') || 
        ipData.reputation.kind.includes('vpn')) {
      await flagAccountForReview(req.body.email, ipData);
    }
    
    // Continue with signup
    // ...
  } catch (error) {
    // Fail open - log error but don't block
    console.error('IP check failed:', error);
  }
});
```

```python
from flask import Flask, request, jsonify

@app.route('/api/signup', methods=['POST'])
def signup():
    # Get client IP
    client_ip = request.headers.get('X-Forwarded-For', '').split(',')[0] or \
                request.remote_addr
    
    try:
        # Check IP intelligence
        ip_data = check_ip_intelligence(client_ip)
        
        # Block risky IPs
        if ip_data['reputation']['risky']:
            return jsonify({
                'error': 'Suspicious IP address detected'
            }), 403
        
        # Flag VPN/hosting users
        if 'hosting' in ip_data['reputation']['kind'] or \
           'vpn' in ip_data['reputation']['kind']:
            flag_account_for_review(request.json['email'], ip_data)
        
        # Continue with signup
        # ...
        
    except Exception as e:
        # Fail open
        app.logger.error(f'IP check failed: {e}')
```

> **Checking Your Own IP**
>
> If you omit the `ip` parameter, the API will automatically check the IP address of the client making the request. This is useful for checking the current user's IP.

## Next Steps [#next-steps]

- [Authentication](/docs/authentication): Learn more about API authentication and security

- [API Reference](/docs/api-reference): Explore complete API documentation

- [Error Handling](/docs/errors): Learn how to handle errors properly

- [Rate Limits](/docs/rate-limits): Understand rate limits and usage tiers


---

# Authentication
URL: https://api-armor.com/docs/authentication

> Learn how to authenticate your API requests using Bearer tokens.

## Overview [#overview]

All API requests to API Shield must be authenticated using an API key. Authentication is handled using the `Authorization` header with a Bearer token.

## Getting Your API Key [#getting-your-api-key]

1. [Sign up for an account](/signup) or [log in](/login)
2. Navigate to your [Dashboard](/dashboard)
3. Go to the **API Keys** section
4. Click &#x2A;*"Create New API Key"**
5. Give your key a descriptive name (e.g., "Production Server", "Development")
6. Copy and securely store your API key

> **Important**
>
> Your API key is shown only once during creation. Make sure to copy it and store it securely. If you lose it, you'll need to generate a new one.

## Using Your API Key [#using-your-api-key]

Include your API key in the `Authorization` header of every request using the Bearer authentication scheme:

```bash
Authorization: Bearer aa_abc123xyz789
```

### Example Requests [#example-requests]

```bash
curl "https://bifrost.api-armor.com/v1/check?email=test@example.com" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const API_KEY = 'aa_abc123xyz789';

fetch('https://bifrost.api-armor.com/v1/check?email=test@example.com', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
})
  .then(res => res.json())
  .then(data => console.log(data));
```

```python
import requests

API_KEY = 'aa_abc123xyz789'

response = requests.get(
    'https://bifrost.api-armor.com/v1/check',
    params={'email': 'test@example.com'},
    headers={'Authorization': f'Bearer {API_KEY}'}
)

data = response.json()
print(data)
```

```go
package main

import (
    "net/http"
)

const API_KEY = "aa_abc123xyz789"

func main() {
    req, _ := http.NewRequest("GET", 
        "https://bifrost.api-armor.com/v1/check?email=test@example.com", 
        nil)
    
    req.Header.Set("Authorization", "Bearer "+API_KEY)
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    // Process response...
}
```

## Security Best Practices [#security-best-practices]

### 1. Use Environment Variables [#1-use-environment-variables]

Never hardcode API keys in your source code. Use environment variables instead:

```javascript
// ✅ Good - Use environment variables
const API_KEY = process.env.API_SHIELD_KEY;

// ❌ Bad - Hardcoded key
const API_KEY = 'aa_abc123xyz789';
```

```python
# ✅ Good - Use environment variables
import os
API_KEY = os.environ.get('API_SHIELD_KEY')

# ❌ Bad - Hardcoded key
API_KEY = 'aa_abc123xyz789'
```

```bash
# Store in .env file (add .env to .gitignore!)
API_SHIELD_KEY=aa_abc123xyz789
```

### 2. Keep Keys Secret [#2-keep-keys-secret]

* Never commit API keys to version control
* Add `.env` to your `.gitignore` file
* Don't expose keys in client-side code
* Use server-side API calls only
* Rotate keys periodically

## Managing API Keys [#managing-api-keys]

### Viewing Your Keys [#viewing-your-keys]

In your [Dashboard](/dashboard/api-keys), you can:

* View all active API keys
* See when each key was created
* Check last used date
* Monitor usage per key

### Revoking Keys [#revoking-keys]

If a key is compromised or no longer needed:

1. Go to your [API Keys Dashboard](/dashboard/api-keys)
2. Find the key you want to revoke
3. Click the &#x2A;*"Delete"*&#x2A; or &#x2A;*"Revoke"** button
4. Confirm the action

> **Important**
>
> Revoking a key immediately stops all requests using that key. Make sure to update your applications before revoking an active key.

## Authentication Errors [#authentication-errors]

### Missing API Key [#missing-api-key]

`401 Unauthorized`

```json
{
  "error": "No API key provided",
  "message": "Please include your API key in the Authorization header"
}
```

### Invalid API Key [#invalid-api-key]

`401 Unauthorized`

```json
{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}
```

### Expired or Revoked Key [#expired-or-revoked-key]

`401 Unauthorized`

```json
{
  "error": "API key revoked",
  "message": "This API key has been revoked. Please generate a new one."
}
```

## Testing Authentication [#testing-authentication]

You can test your authentication setup with this simple request:

```bash
curl "https://bifrost.api-armor.com/v1/check?email=test@example.com" \
  -H "Authorization: Bearer aa_abc123xyz789" \
  -v
```

A successful authentication will return a `200 OK` status code.

## Next Steps [#next-steps]

- [Quick Start](/docs/quick-start): Get started with your first API request

- [API Reference](/docs/api-reference): Explore the complete API documentation

- [Error Handling](/docs/errors): Learn about error responses


---

# API Reference
URL: https://api-armor.com/docs/api-reference

> Complete reference documentation for the API Shield API endpoints.

## Base URL [#base-url]

All API requests should be made to:

```
https://bifrost.api-armor.com
```

## Authentication [#authentication]

All endpoints require authentication using a Bearer token in the `Authorization` header.

```bash
Authorization: Bearer aa_abc123xyz789
```

See the [Authentication](/docs/authentication) guide for more details.

## Endpoints [#endpoints]

- [Check Email](/docs/api-reference/check-email): Verify if an email address uses a disposable domain

- [Check IP Intelligence](/docs/api-reference/check-ip-reputation): Get IP address intelligence with reputation scoring and geolocation data

## Response Format [#response-format]

All API responses are returned in JSON format with appropriate HTTP status codes.

### Success Response [#success-response]

`200 OK`

Successful requests return a `200 OK` status code with the response data:

```json
{
  "email": "user@example.com",
  "is_disposable": false,
  "domain": "example.com"
}
```

### Error Response [#error-response]

Error responses include an `error` field with a machine-readable error code and a `message` field with a human-readable description:

```json
{
  "error": "invalid_email",
  "message": "The provided email address is not valid"
}
```

## Common Headers [#common-headers]

### Request Headers [#request-headers]

| Header          | Required | Description                                 |
| --------------- | -------- | ------------------------------------------- |
| `Authorization` | Yes      | Bearer token for authentication             |
| `Content-Type`  | No       | Set to `application/json` for POST requests |

### Response Headers [#response-headers]

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `Content-Type`          | Always `application/json`                 |
| `X-RateLimit-Limit`     | Maximum requests allowed per time window  |
| `X-RateLimit-Remaining` | Remaining requests in current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets |

## HTTP Status Codes [#http-status-codes]

| Status Code | Description                                           |
| ----------- | ----------------------------------------------------- |
| `200`       | Request successful                                    |
| `400`       | Bad request - Invalid parameters                      |
| `401`       | Unauthorized - Invalid or missing API key             |
| `403`       | Forbidden - API key doesn't have required permissions |
| `429`       | Too many requests - Rate limit exceeded               |
| `500`       | Internal server error                                 |
| `503`       | Service unavailable                                   |

See the [Error Handling](/docs/errors) guide for detailed error information.

## Rate Limiting [#rate-limiting]

API requests are rate-limited based on your subscription plan. Rate limit information is included in response headers.

See the [Rate Limits](/docs/rate-limits) guide for more details.

## Next Steps [#next-steps]

- [Check Email](/docs/api-reference/check-email): Learn how to check if an email is disposable

- [Check IP Intelligence](/docs/api-reference/check-ip-reputation): Get IP address intelligence and geolocation data

- [Error Handling](/docs/errors): Handle errors gracefully in your application

- [Rate Limits](/docs/rate-limits): Understand rate limiting


---

# Check Email
URL: https://api-armor.com/docs/api-reference/check-email

> Verify if an email address uses a disposable or temporary domain.

## Check Email Endpoint [#check-email-endpoint]

`GET https://bifrost.api-armor.com/v1/check`

Checks whether an email address uses a disposable, temporary, or throwaway domain.

## Parameters [#parameters]

### Query Parameters [#query-parameters]

| Parameter | Type   | Required | Description                                               |
| --------- | ------ | -------- | --------------------------------------------------------- |
| `email`   | string | Yes      | The email address to check. Must be a valid email format. |

## Request Examples [#request-examples]

```bash
curl "https://bifrost.api-armor.com/v1/check?email=layohe8924@badfist.com" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const email = 'layohe8924@badfist.com';

const response = await fetch(
  `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
  {
    headers: {
      'Authorization': 'Bearer aa_abc123xyz789'
    }
  }
);

const data = await response.json();
console.log(data);
```

```python
import requests

email = 'layohe8924@badfist.com'

response = requests.get(
    'https://bifrost.api-armor.com/v1/check',
    params={'email': email},
    headers={'Authorization': 'Bearer aa_abc123xyz789'}
)

data = response.json()
print(data)
```

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func checkEmail(apiKey, email string) error {
    baseURL := "https://bifrost.api-armor.com/v1/check"
    
    params := url.Values{}
    params.Add("email", email)
    
    req, err := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    if err != nil {
        return err
    }
    
    req.Header.Set("Authorization", "Bearer "+apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
    
    return nil
}

func main() {
    checkEmail("aa_abc123xyz789", "layohe8924@badfist.com")
}
```

```php
<?php

$apiKey = 'aa_abc123xyz789';
$email = 'layohe8924@badfist.com';

$url = 'https://bifrost.api-armor.com/v1/check?' . http_build_query([
    'email' => $email
]);

$options = [
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer $apiKey\r\n"
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);

print_r($data);
```

```ruby
require 'net/http'
require 'uri'
require 'json'

api_key = 'aa_abc123xyz789'
email = 'layohe8924@badfist.com'

uri = URI('https://bifrost.api-armor.com/v1/check')
uri.query = URI.encode_www_form(email: email)

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data
```

```java
import java.net.http.*;
import java.net.*;
import java.io.IOException;

public class APIShieldClient {
    private static final String API_KEY = "aa_abc123xyz789";
    private static final String BASE_URL = "https://bifrost.api-armor.com/v1/check";
    
    public static void checkEmail(String email) throws IOException, InterruptedException {
        String url = BASE_URL + "?email=" + URLEncoder.encode(email, "UTF-8");
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();
        
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
    
    public static void main(String[] args) throws Exception {
        checkEmail("layohe8924@badfist.com");
    }
}
```

```rust
use reqwest;
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = "aa_abc123xyz789";
    let email = "layohe8924@badfist.com";
    
    let client = reqwest::Client::new();
    let url = format!("https://bifrost.api-armor.com/v1/check?email={}", email);
    
    let response = client
        .get(&url)
        .header("Authorization", format!("Bearer {}", api_key))
        .send()
        .await?;
    
    let data: Value = response.json().await?;
    println!("{:#?}", data);
    
    Ok(())
}
```

## Response [#response]

### Success Response [#success-response]

`200 OK`

Returns information about the email address and whether it's from a disposable domain.

```json
{
  "email": "layohe8924@badfist.com",
  "is_disposable": true,
  "domain": "badfist.com",
  "free_email": false
}
```

#### Response Fields [#response-fields]

| Field           | Type    | Description                                                                                          |
| --------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `email`         | string  | The email address that was checked                                                                   |
| `is_disposable` | boolean | `true` if the domain is identified as disposable, `false` otherwise                                  |
| `domain`        | string  | The domain portion of the email address                                                              |
| `free_email`    | boolean | `true` if the domain is a known free email provider (e.g., Gmail, Yahoo, Outlook), `false` otherwise |

### Example Responses [#example-responses]

**Disposable Email:**

```json
{
  "email": "user@tempmail.com",
  "is_disposable": true,
  "domain": "tempmail.com",
  "free_email": false
}
```

**Free Email Provider (Gmail):**

```json
{
  "email": "user@gmail.com",
  "is_disposable": false,
  "domain": "gmail.com",
  "free_email": true
}
```

**Business Email:**

```json
{
  "email": "user@company.com",
  "is_disposable": false,
  "domain": "company.com",
  "free_email": false
}
```

## Error Responses [#error-responses]

### Invalid Email Format [#invalid-email-format]

`400 Bad Request`

```json
{
  "error": "invalid_email",
  "message": "The provided email address is not valid"
}
```

### Missing Email Parameter [#missing-email-parameter]

`400 Bad Request`

```json
{
  "error": "missing_parameter",
  "message": "The 'email' parameter is required"
}
```

### Unauthorized [#unauthorized]

`401 Unauthorized`

```json
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
```

### Rate Limit Exceeded [#rate-limit-exceeded]

`429 Too Many Requests`

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```

> **Rate Limit Headers**
>
> When you receive a 429 error, check the `X-RateLimit-Reset` header to see when you can make requests again.

## Integration Examples [#integration-examples]

### Form Validation [#form-validation]

```javascript
import { useState } from 'react';

function EmailInput({ onValidate }) {
  const [email, setEmail] = useState('');
  const [isChecking, setIsChecking] = useState(false);
  const [error, setError] = useState('');

  const checkEmail = async (email) => {
    setIsChecking(true);
    setError('');

    try {
      const response = await fetch(
        `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.REACT_APP_API_SHIELD_KEY}`
          }
        }
      );

      const data = await response.json();

      if (data.is_disposable) {
        setError('Disposable email addresses are not allowed');
        return false;
      }

      return true;
    } catch (err) {
      console.error('Email check failed:', err);
      return true; // Fail open
    } finally {
      setIsChecking(false);
    }
  };

  const handleBlur = async () => {
    if (email) {
      const isValid = await checkEmail(email);
      onValidate?.(email, isValid);
    }
  };

  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        onBlur={handleBlur}
        disabled={isChecking}
      />
      {isChecking && <span>Checking...</span>}
      {error && <span className="error">{error}</span>}
    </div>
  );
}
```

```python
from django.http import JsonResponse
import requests
import os

API_KEY = os.environ.get('API_SHIELD_KEY')

def check_disposable_email(email):
    """Check if email is from a disposable domain"""
    try:
        response = requests.get(
            'https://bifrost.api-armor.com/v1/check',
            params={'email': email},
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=5
        )
        response.raise_for_status()
        data = response.json()
        return data.get('is_disposable', False)
    except Exception as e:
        # Log error and fail open
        print(f"Email validation error: {e}")
        return False

def signup_view(request):
    if request.method == 'POST':
        email = request.POST.get('email')
        
        if check_disposable_email(email):
            return JsonResponse({
                'error': 'Disposable email addresses are not allowed'
            }, status=400)
        
        # Continue with signup
        # ...
        
        return JsonResponse({'success': True})
```

## Best Practices [#best-practices]

### 1. Fail Open [#1-fail-open]

If the API is unavailable, allow the request to proceed rather than blocking users:

```python
def is_disposable_email(email):
    try:
        # API call with timeout
        result = check_email_api(email, timeout=5)
        return result['is_disposable']
    except Exception as e:
        # Log error but don't block user
        logger.error(f"Email check failed: {e}")
        return False  # Fail open
```

### 2. Async Validation [#2-async-validation]

For better UX, validate emails asynchronously after submission:

```javascript
async function handleSignup(userData) {
  // Create user account immediately
  const user = await createUser(userData);
  
  // Check email asynchronously
  checkEmail(userData.email).then(result => {
    if (result.is_disposable) {
      // Flag account for review
      flagAccountForReview(user.id);
      sendWarningEmail(user.email);
    }
  });
  
  return user;
}
```

## Next Steps [#next-steps]

- [IP Intelligence](/docs/api-reference/check-ip-reputation): Get IP address intelligence and geolocation data

- [Error Handling](/docs/errors): Learn how to handle API errors

- [Rate Limits](/docs/rate-limits): Understand rate limiting


---

# Check IP Intelligence
URL: https://api-armor.com/docs/api-reference/check-ip-reputation

> Get IP address intelligence including reputation scoring and detailed geolocation information.

## IP Intelligence Endpoint [#ip-intelligence-endpoint]

`GET https://bifrost.api-armor.com/v1/ip-reputation-check`

Checks an IP address for reputation risk and returns detailed geolocation information. If no IP parameter is provided, the request will check the client's own IP address.

### Features [#features]

* **Real-time reputation scoring** from threat intelligence databases
* **Detailed geolocation data** (country, city, coordinates, timezone)
* **ISP and organization information**
* **Network classification** (hosting, VPN, residential, etc.)
* **Bot and attack report statistics**

> **Private IP Handling**
>
> Private IP addresses (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.) are automatically detected and return a clean reputation without external lookups.

## Parameters [#parameters]

### Query Parameters [#query-parameters]

| Parameter | Type   | Required | Description                                                                               |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `ip`      | string | No       | The IPv4 address to check. If not provided, checks the client's IP address automatically. |

## Request Examples [#request-examples]

```bash
curl "https://bifrost.api-armor.com/v1/ip-reputation-check?ip=159.89.165.46" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```bash
# Omit the ip parameter to check your own IP
curl "https://bifrost.api-armor.com/v1/ip-reputation-check" \
  -H "Authorization: Bearer aa_abc123xyz789"
```

```javascript
const ip = '159.89.165.46';

const response = await fetch(
  `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${encodeURIComponent(ip)}`,
  {
    headers: {
      'Authorization': 'Bearer aa_abc123xyz789'
    }
  }
);

const data = await response.json();
console.log(data);
```

```python
import requests

ip = '159.89.165.46'

response = requests.get(
    'https://bifrost.api-armor.com/v1/ip-reputation-check',
    params={'ip': ip},
    headers={'Authorization': 'Bearer aa_abc123xyz789'}
)

data = response.json()
print(data)
```

```go
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func checkIPReputation(apiKey, ip string) error {
    baseURL := "https://bifrost.api-armor.com/v1/ip-reputation-check"
    
    params := url.Values{}
    params.Add("ip", ip)
    
    req, err := http.NewRequest("GET", baseURL+"?"+params.Encode(), nil)
    if err != nil {
        return err
    }
    
    req.Header.Set("Authorization", "Bearer "+apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
    
    return nil
}

func main() {
    checkIPReputation("aa_abc123xyz789", "159.89.165.46")
}
```

```php
<?php

$apiKey = 'aa_abc123xyz789';
$ip = '159.89.165.46';

$url = 'https://bifrost.api-armor.com/v1/ip-reputation-check?' . http_build_query([
    'ip' => $ip
]);

$options = [
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer $apiKey\r\n"
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$data = json_decode($response, true);

print_r($data);
```

```ruby
require 'net/http'
require 'uri'
require 'json'

api_key = 'aa_abc123xyz789'
ip = '159.89.165.46'

uri = URI('https://bifrost.api-armor.com/v1/ip-reputation-check')
uri.query = URI.encode_www_form(ip: ip)

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data
```

```java
import java.net.http.*;
import java.net.*;
import java.io.IOException;

public class APIArmorClient {
    private static final String API_KEY = "aa_abc123xyz789";
    private static final String BASE_URL = "https://bifrost.api-armor.com/v1/ip-reputation-check";
    
    public static void checkIPReputation(String ip) throws IOException, InterruptedException {
        String url = BASE_URL + "?ip=" + URLEncoder.encode(ip, "UTF-8");
        
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + API_KEY)
            .GET()
            .build();
        
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
    
    public static void main(String[] args) throws Exception {
        checkIPReputation("159.89.165.46");
    }
}
```

```rust
use reqwest;
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = "aa_abc123xyz789";
    let ip = "159.89.165.46";
    
    let client = reqwest::Client::new();
    let url = format!("https://bifrost.api-armor.com/v1/ip-reputation-check?ip={}", ip);
    
    let response = client
        .get(&url)
        .header("Authorization", format!("Bearer {}", api_key))
        .send()
        .await?;
    
    let data: Value = response.json().await?;
    println!("{:#?}", data);
    
    Ok(())
}
```

## Response [#response]

### Success Response [#success-response]

`200 OK`

Returns comprehensive IP intelligence including geolocation and reputation data.

```json
{
  "ip": "164.92.87.190",
  "country": "United States",
  "country_code": "US",
  "flag": "🇺🇸",
  "region": "CA",
  "region_name": "California",
  "city": "Santa Clara",
  "subdivisions": "Santa Clara",
  "connection_type": "Corporate",
  "is_anycast": false,
  "zip": "95054",
  "latitude": 37.3986,
  "longitude": -121.964,
  "timezone": "America/Los_Angeles",
  "isp": "DigitalOcean, LLC",
  "organization": "DigitalOcean, LLC",
  "asn": "AS14061 DigitalOcean, LLC",
  "reputation": {
    "risky": true,
    "reputation": "suspicious",
    "bot": 1,
    "probe": 27,
    "rate": 0,
    "attack": 0,
    "crawler": 0,
    "sum": 28,
    "kind": ["hosting"]
  }
}
```

#### Response Fields [#response-fields]

| Field             | Type    | Description                                                    |
| ----------------- | ------- | -------------------------------------------------------------- |
| `ip`              | string  | The IP address that was checked                                |
| `country`         | string  | Country name                                                   |
| `country_code`    | string  | ISO 3166-1 alpha-2 country code                                |
| `flag`            | string  | Country flag emoji                                             |
| `region`          | string  | Region or state code                                           |
| `region_name`     | string  | Full region or state name                                      |
| `city`            | string  | City name                                                      |
| `subdivisions`    | string  | Administrative subdivisions                                    |
| `connection_type` | string  | Type of internet connection (e.g., "Corporate", "Residential") |
| `is_anycast`      | boolean | Whether the IP is an anycast address                           |
| `zip`             | string  | Postal/ZIP code                                                |
| `latitude`        | number  | Geographic latitude coordinate                                 |
| `longitude`       | number  | Geographic longitude coordinate                                |
| `timezone`        | string  | IANA timezone identifier                                       |
| `isp`             | string  | Internet Service Provider name                                 |
| `organization`    | string  | Organization name                                              |
| `asn`             | string  | Autonomous System Number and organization                      |
| `reputation`      | object  | Reputation details (see below)                                 |

#### Reputation Object [#reputation-object]

| Field        | Type    | Description                                                                                                              |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `risky`      | boolean | Whether the IP is considered risky based on threat intelligence                                                          |
| `reputation` | string  | Reputation level: `"bad"`, `"warning"`, `"suspicious"`, `"informative"`, or `"ok"`                                       |
| `bot`        | integer | Number of bot activity reports                                                                                           |
| `probe`      | integer | Number of network probing reports                                                                                        |
| `rate`       | integer | Number of rate limiting/abuse reports                                                                                    |
| `attack`     | integer | Number of attack reports                                                                                                 |
| `crawler`    | integer | Number of crawler/scraping reports                                                                                       |
| `sum`        | integer | Total sum of all reports                                                                                                 |
| `kind`       | array   | Network classification types (e.g., `"hosting"`, `"vpn"`, `"scanner"`, `"crawler"`, `"isp"`, `"education"`, `"dynamic"`) |

### Example Responses [#example-responses]

**Risky IP from Hosting Provider:**

```json
{
  "ip": "164.92.87.190",
  "country": "United States",
  "country_code": "US",
  "flag": "🇺🇸",
  "region": "CA",
  "region_name": "California",
  "city": "Santa Clara",
  "subdivisions": "Santa Clara",
  "connection_type": "Corporate",
  "is_anycast": false,
  "zip": "95054",
  "latitude": 37.3986,
  "longitude": -121.964,
  "timezone": "America/Los_Angeles",
  "isp": "DigitalOcean, LLC",
  "organization": "DigitalOcean, LLC",
  "asn": "AS14061 DigitalOcean, LLC",
  "reputation": {
    "risky": true,
    "reputation": "suspicious",
    "bot": 1,
    "probe": 27,
    "rate": 0,
    "attack": 0,
    "crawler": 0,
    "sum": 28,
    "kind": ["hosting"]
  }
}
```

**Clean IP Address:**

```json
{
  "ip": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "flag": "🇺🇸",
  "region": "CA",
  "region_name": "California",
  "city": "Mountain View",
  "subdivisions": "",
  "connection_type": "Corporate",
  "is_anycast": true,
  "zip": "94035",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "isp": "Google LLC",
  "organization": "Google LLC",
  "asn": "AS15169 Google LLC",
  "reputation": {
    "risky": false,
    "reputation": "ok",
    "bot": 0,
    "probe": 0,
    "rate": 0,
    "attack": 0,
    "crawler": 0,
    "sum": 0,
    "kind": []
  }
}
```

**Private IP Address:**

```json
{
  "ip": "192.168.1.1",
  "country": "",
  "country_code": "",
  "region": "",
  "region_name": "",
  "city": "",
  "subdivisions": "",
  "connection_type": "",
  "is_anycast": false,
  "zip": "",
  "latitude": 0,
  "longitude": 0,
  "timezone": "",
  "isp": "",
  "organization": "",
  "asn": "",
  "reputation": {
    "risky": false,
    "reputation": "ok",
    "bot": 0,
    "probe": 0,
    "rate": 0,
    "attack": 0,
    "crawler": 0,
    "sum": 0,
    "kind": []
  }
}
```

## Error Responses [#error-responses]

### Invalid IP Format [#invalid-ip-format]

`400 Bad Request`

```json
{
  "error": "invalid_ip",
  "message": "invalid IP address format"
}
```

### Unauthorized [#unauthorized]

`401 Unauthorized`

```json
{
  "error": "invalid_api_key",
  "message": "The provided API key is not valid"
}
```

### Rate Limit Exceeded [#rate-limit-exceeded]

`429 Too Many Requests`

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```

### Quota Exceeded [#quota-exceeded]

`429 Too Many Requests`

```json
{
  "error": "quota_exceeded",
  "message": "Monthly quota exceeded. Please upgrade your plan or wait until next month.",
  "retry_after": 86400
}
```

> **Rate Limit Headers**
>
> When you receive a 429 error, check the `X-RateLimit-Reset` header to see when you can make requests again. The response also includes quota information in `X-Quota-Limit`, `X-Quota-Remaining`, and `X-Quota-Reset` headers.

## Understanding IP Intelligence Scores [#understanding-ip-intelligence-scores]

The `reputation` field indicates the overall risk level:

| Level         | Description                   | Action                                   |
| ------------- | ----------------------------- | ---------------------------------------- |
| `bad`         | Confirmed malicious activity  | Block immediately                        |
| `warning`     | High risk, multiple reports   | Block or require additional verification |
| `suspicious`  | Moderate risk, some reports   | Consider additional verification         |
| `informative` | Low risk, minimal reports     | Monitor but allow                        |
| `ok`          | Clean, no significant reports | Allow                                    |

## Network Classification Types [#network-classification-types]

The `kind` array provides network classification:

| Type        | Description                     |
| ----------- | ------------------------------- |
| `hosting`   | Data center or hosting provider |
| `vpn`       | VPN service endpoint            |
| `scanner`   | Known scanning/probing source   |
| `crawler`   | Web crawler or bot              |
| `isp`       | Internet Service Provider       |
| `education` | Educational institution         |
| `dynamic`   | Dynamic IP range                |

## Integration Examples [#integration-examples]

### User Signup Protection [#user-signup-protection]

```javascript
import express from 'express';

const app = express();
const API_KEY = process.env.API_ARMOR_KEY;

app.post('/api/signup', async (req, res) => {
  // Get client IP (handle proxies)
  const clientIP = req.headers['x-forwarded-for']?.split(',')[0] || 
                   req.socket.remoteAddress;

  try {
    // Check IP reputation
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${clientIP}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const ipData = await response.json();

    // Block if risky
    if (ipData.reputation.risky) {
      return res.status(403).json({
        error: 'signup_blocked',
        message: 'Signup from suspicious IP address blocked'
      });
    }

    // Flag for review if hosting/VPN
    if (ipData.reputation.kind.includes('hosting') || 
        ipData.reputation.kind.includes('vpn')) {
      // Mark account for manual review
      await flagAccountForReview(req.body.email, ipData);
    }

    // Continue with signup
    // ...

    res.json({ success: true });
  } catch (error) {
    // Fail open - don't block users due to API errors
    console.error('IP check failed:', error);
    // Continue with signup
  }
});
```

```python
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
API_KEY = os.environ.get('API_ARMOR_KEY')

def get_client_ip():
    """Get the client's real IP address"""
    if request.headers.get('X-Forwarded-For'):
        return request.headers.get('X-Forwarded-For').split(',')[0]
    return request.remote_addr

@app.route('/api/signup', methods=['POST'])
def signup():
    client_ip = get_client_ip()
    
    try:
        # Check IP reputation
        response = requests.get(
            'https://bifrost.api-armor.com/v1/ip-reputation-check',
            params={'ip': client_ip},
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=5
        )
        response.raise_for_status()
        ip_data = response.json()
        
        # Block risky IPs
        if ip_data['reputation']['risky']:
            return jsonify({
                'error': 'signup_blocked',
                'message': 'Signup from suspicious IP address blocked'
            }), 403
        
        # Flag VPN/hosting users
        if 'hosting' in ip_data['reputation']['kind'] or \
           'vpn' in ip_data['reputation']['kind']:
            flag_account_for_review(request.json['email'], ip_data)
        
        # Continue with signup
        # ...
        
        return jsonify({'success': True})
        
    except Exception as e:
        # Fail open - log error but don't block user
        app.logger.error(f'IP check failed: {e}')
        # Continue with signup
        return jsonify({'success': True})
```

### Rate Limiting Enhancement [#rate-limiting-enhancement]

```javascript
import rateLimit from 'express-rate-limit';

// Dynamic rate limiting based on IP reputation
async function getIPReputation(ip) {
  try {
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${ip}`,
      {
        headers: { 'Authorization': `Bearer ${process.env.API_ARMOR_KEY}` }
      }
    );
    return await response.json();
  } catch (error) {
    return null;
  }
}

// Create adaptive rate limiter
const adaptiveRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: async (req) => {
    const clientIP = req.headers['x-forwarded-for']?.split(',')[0] || 
                     req.socket.remoteAddress;
    
    const ipData = await getIPReputation(clientIP);
    
    if (!ipData) return 100; // Default if check fails
    
    // Adjust limits based on reputation
    if (ipData.reputation.reputation === 'bad') return 10;
    if (ipData.reputation.reputation === 'suspicious') return 50;
    if (ipData.reputation.kind.includes('hosting')) return 30;
    
    return 100; // Normal limit for clean IPs
  },
  message: 'Too many requests from this IP'
});

app.use('/api/', adaptiveRateLimit);
```

### Login Protection [#login-protection]

```python
from django.contrib.auth import authenticate, login
from django.http import JsonResponse
import requests
import os

API_KEY = os.environ.get('API_ARMOR_KEY')

def check_ip_reputation(ip):
    """Check IP reputation"""
    try:
        response = requests.get(
            'https://bifrost.api-armor.com/v1/ip-reputation-check',
            params={'ip': ip},
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=5
        )
        response.raise_for_status()
        return response.json()
    except Exception as e:
        print(f"IP check error: {e}")
        return None

def get_client_ip(request):
    """Extract client IP from request"""
    x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
    if x_forwarded_for:
        return x_forwarded_for.split(',')[0]
    return request.META.get('REMOTE_ADDR')

def login_view(request):
    if request.method == 'POST':
        username = request.POST.get('username')
        password = request.POST.get('password')
        client_ip = get_client_ip(request)
        
        # Check IP reputation
        ip_data = check_ip_reputation(client_ip)
        
        if ip_data and ip_data['reputation']['risky']:
            # Require 2FA for risky IPs
            return JsonResponse({
                'requires_2fa': True,
                'message': 'Additional verification required'
            })
        
        # Check for attack patterns
        if ip_data and ip_data['reputation']['attack'] > 5:
            # Block or require captcha
            return JsonResponse({
                'error': 'verification_required',
                'message': 'Please complete verification'
            }, status=403)
        
        # Normal login flow
        user = authenticate(request, username=username, password=password)
        if user:
            login(request, user)
            return JsonResponse({'success': True})
        
        return JsonResponse({'error': 'Invalid credentials'}, status=401)
```

## Best Practices [#best-practices]

### 1. Fail Open for Availability [#1-fail-open-for-availability]

Always fail open if the API is unavailable to avoid blocking legitimate users:

```javascript
async function checkIPSafety(ip) {
  try {
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${ip}`,
      {
        headers: { 'Authorization': `Bearer ${process.env.API_ARMOR_KEY}` },
        timeout: 5000 // 5 second timeout
      }
    );
    return await response.json();
  } catch (error) {
    console.error('IP check failed:', error);
    // Return safe default - don't block users
    return { reputation: { risky: false, reputation: 'ok' } };
  }
}
```

### 2. Implement Risk-Based Actions [#2-implement-risk-based-actions]

Don't just block - use reputation data for smart decisions:

```javascript
function getRiskAction(ipData) {
  const { reputation } = ipData.reputation;
  
  switch (reputation) {
    case 'bad':
      return 'block';
    case 'warning':
      return 'require_2fa';
    case 'suspicious':
      return 'require_captcha';
    default:
      return 'allow';
  }
}
```

### 3. Cache Results [#3-cache-results]

Cache IP reputation data to reduce API calls and improve performance:

```javascript
import NodeCache from 'node-cache';

const ipCache = new NodeCache({ stdTTL: 3600 }); // 1 hour cache

async function getCachedIPReputation(ip) {
  // Check cache first
  const cached = ipCache.get(ip);
  if (cached) return cached;
  
  // Fetch if not cached
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/ip-reputation-check?ip=${ip}`,
    {
      headers: { 'Authorization': `Bearer ${process.env.API_ARMOR_KEY}` }
    }
  );
  
  const data = await response.json();
  ipCache.set(ip, data);
  
  return data;
}
```

### 4. Handle Proxies Correctly [#4-handle-proxies-correctly]

Extract the real client IP when behind proxies:

```javascript
function getClientIP(request) {
  // Check X-Forwarded-For header (common with proxies/load balancers)
  const forwardedFor = request.headers['x-forwarded-for'];
  if (forwardedFor) {
    // Take first IP in the chain (client IP)
    return forwardedFor.split(',')[0].trim();
  }
  
  // Check X-Real-IP header (Nginx)
  const realIP = request.headers['x-real-ip'];
  if (realIP) return realIP;
  
  // Fall back to direct connection
  return request.socket.remoteAddress;
}
```

### 5. Log and Monitor [#5-log-and-monitor]

Log reputation checks for analysis and monitoring:

```javascript
async function checkAndLogIP(ip, context) {
  const ipData = await checkIPReputation(ip);
  
  // Log the check
  await logEvent({
    type: 'ip_reputation_check',
    ip: ip,
    context: context,
    reputation: ipData.reputation,
    location: {
      country: ipData.country,
      city: ipData.city,
      isp: ipData.isp
    },
    timestamp: new Date()
  });
  
  return ipData;
}
```

## Use Cases [#use-cases]

### Content Access Control [#content-access-control]

Block access to premium content from known VPN/proxy services:

```javascript
if (ipData.reputation.kind.includes('vpn') || 
    ipData.reputation.kind.includes('hosting')) {
  return res.status(403).json({
    error: 'vpn_detected',
    message: 'Premium content not available via VPN/proxy'
  });
}
```

### Geographic Restrictions [#geographic-restrictions]

Enforce geo-restrictions based on IP location:

```javascript
const allowedCountries = ['US', 'CA', 'GB'];

if (!allowedCountries.includes(ipData.country_code)) {
  return res.status(451).json({
    error: 'geo_restricted',
    message: 'Service not available in your country'
  });
}
```

### Bot Detection [#bot-detection]

Identify and handle bot traffic:

```javascript
if (ipData.reputation.bot > 0 || 
    ipData.reputation.crawler > 0) {
  // Serve cached/simplified version to bots
  return serveStaticContent(req, res);
}
```

## Next Steps [#next-steps]

- [Check Email](/docs/api-reference/check-email): Validate email addresses and detect disposable domains

- [Error Handling](/docs/errors): Learn how to handle API errors

- [Rate Limits](/docs/rate-limits): Understand rate limiting and quotas

- [Quick Start](/docs/quick-start): Integration examples and best practices


---

# Error Handling
URL: https://api-armor.com/docs/errors

> Learn how to handle errors and understand error responses from the API Shield API.

## Overview [#overview]

API Shield uses conventional HTTP status codes to indicate the success or failure of API requests. Errors are returned with descriptive error messages to help you diagnose and fix issues.

## Error Response Format [#error-response-format]

All error responses follow a consistent JSON format:

```json
{
  "error": "error_code",
  "message": "Human-readable error description"
}
```

### Error Response Fields [#error-response-fields]

| Field         | Type   | Description                                                        |
| ------------- | ------ | ------------------------------------------------------------------ |
| `error`       | string | Machine-readable error code for programmatic handling              |
| `message`     | string | Human-readable error description                                   |
| `retry_after` | number | (Optional) Seconds to wait before retrying (for rate limit errors) |

## HTTP Status Codes [#http-status-codes]

### Success Codes [#success-codes]

`200 OK`

The request was successful and the response contains the requested data.

### Client Error Codes [#client-error-codes]

`400 Bad Request`

The request was invalid or cannot be served. Check the error message for details about what's wrong with the request.

**Common causes:**

* Invalid email format
* Missing required parameters
* Malformed request

`401 Unauthorized`

Authentication failed. The API key is missing, invalid, or has been revoked.

**Common causes:**

* Missing `Authorization` header
* Invalid API key
* Expired or revoked API key

`403 Forbidden`

The API key is valid but doesn't have permission to perform the requested action.

**Common causes:**

* Account suspended
* API key permissions insufficient
* Subscription expired

`404 Not Found`

The requested endpoint does not exist.

**Common causes:**

* Incorrect URL
* Typo in endpoint path

`429 Too Many Requests`

Rate limit exceeded. Too many requests have been made in a given time period.

**Response includes:**

* `retry_after` field indicating seconds to wait
* `X-RateLimit-Reset` header with reset timestamp

### Server Error Codes [#server-error-codes]

`500 Internal Server Error`

An error occurred on the server. If this persists, contact support.

`503 Service Unavailable`

The service is temporarily unavailable. Typically due to maintenance or high load.

## Error Types [#error-types]

### Invalid Email [#invalid-email]

`400 Bad Request`

```json
{
  "error": "invalid_email",
  "message": "The provided email address is not valid"
}
```

**Cause:** The email parameter is not a valid email format.

**Solution:** Validate email format before sending to the API.

```javascript
function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}
```

### Missing Parameter [#missing-parameter]

`400 Bad Request`

```json
{
  "error": "missing_parameter",
  "message": "The 'email' parameter is required"
}
```

**Cause:** Required parameter is missing from the request.

**Solution:** Ensure all required parameters are included in your request.

### Invalid IP Address [#invalid-ip-address]

`400 Bad Request`

```json
{
  "error": "invalid_ip",
  "message": "invalid IP address format"
}
```

**Cause:** The IP parameter is not a valid IPv4 address format.

**Solution:** Validate IP format before sending to the API.

```javascript
function isValidIPv4(ip) {
  return /^(\d{1,3}\.){3}\d{1,3}$/.test(ip);
}
```

### Invalid API Key [#invalid-api-key]

`401 Unauthorized`

```json
{
  "error": "invalid_api_key",
  "message": "The provided API key is not valid"
}
```

**Cause:** The API key in the Authorization header is invalid.

**Solution:**

* Verify your API key is correct
* Check for extra spaces or characters
* Ensure you're using `Bearer aa_abc123xyz789` format (API keys are prefixed with `aa_`)

### API Key Revoked [#api-key-revoked]

`401 Unauthorized`

```json
{
  "error": "api_key_revoked",
  "message": "This API key has been revoked"
}
```

**Cause:** The API key has been revoked in the dashboard.

**Solution:** Generate a new API key in your [dashboard](/dashboard/api-keys).

### Rate Limit Exceeded [#rate-limit-exceeded]

`429 Too Many Requests`

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```

**Cause:** Too many requests in the current time window.

**Solution:**

* Implement rate limiting in your application
* Use exponential backoff for retries
* Cache results to reduce API calls
* Upgrade your plan for higher limits

### Internal Server Error [#internal-server-error]

`500 Internal Server Error`

```json
{
  "error": "internal_server_error",
  "message": "An unexpected error occurred. Please try again."
}
```

**Cause:** An error occurred on our servers.

**Solution:**

* Retry the request after a short delay
* If the problem persists, contact support

### Service Unavailable [#service-unavailable]

`503 Service Unavailable`

```json
{
  "error": "service_unavailable",
  "message": "The service is temporarily unavailable"
}
```

**Cause:** The API is temporarily unavailable, usually due to maintenance.

**Solution:**

* Retry with exponential backoff
* Check our status page for maintenance schedules

## Error Handling Best Practices [#error-handling-best-practices]

### 1. Always Check Status Codes [#1-always-check-status-codes]

```javascript
const response = await fetch(
  'https://bifrost.api-armor.com/v1/check?email=test@example.com',
  {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  }
);

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error);
  throw new Error(error.message);
}

const data = await response.json();
```

### 2. Implement Retry Logic with Exponential Backoff [#2-implement-retry-logic-with-exponential-backoff]

```javascript
async function checkEmailWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
        {
          headers: { 'Authorization': `Bearer ${API_KEY}` }
        }
      );

      if (response.ok) {
        return await response.json();
      }

      // Don't retry on client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Retry on server errors (5xx) with exponential backoff
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      throw new Error(`Server error: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}
```

### 3. Handle Rate Limits Gracefully [#3-handle-rate-limits-gracefully]

```javascript
async function checkEmailWithRateLimit(email) {
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  if (response.status === 429) {
    const error = await response.json();
    const retryAfter = error.retry_after || 60;
    
    console.log(`Rate limited. Retrying after ${retryAfter} seconds`);
    
    // Wait and retry
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return checkEmailWithRateLimit(email);
  }

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return await response.json();
}
```

### 4. Fail Open for Better UX [#4-fail-open-for-better-ux]

When the API is unavailable, consider allowing the operation to proceed rather than blocking users:

```python
def check_email_safely(email):
    """Check email with graceful degradation"""
    try:
        response = requests.get(
            'https://bifrost.api-armor.com/v1/check',
            params={'email': email},
            headers={'Authorization': f'Bearer {API_KEY}'},
            timeout=5  # Set a reasonable timeout
        )
        
        if response.status_code == 200:
            data = response.json()
            return data['is_disposable']
        
        # For 5xx errors, fail open
        if response.status_code >= 500:
            logger.warning(f"API unavailable: {response.status_code}")
            return False  # Assume not disposable
        
        # For 4xx errors, fail closed or raise
        response.raise_for_status()
        
    except requests.exceptions.Timeout:
        logger.warning("API timeout - failing open")
        return False  # Fail open on timeout
    
    except Exception as e:
        logger.error(f"Email check failed: {e}")
        return False  # Fail open on unexpected errors
```

### 5. Log Errors for Debugging [#5-log-errors-for-debugging]

```javascript
async function checkEmail(email) {
  try {
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    if (!response.ok) {
      const error = await response.json();
      
      // Log error details
      console.error('API Error:', {
        status: response.status,
        error: error.error,
        message: error.message,
        email: email,
        timestamp: new Date().toISOString()
      });
      
      // Send to error tracking service
      // trackError(error);
      
      throw error;
    }

    return await response.json();
  } catch (error) {
    // Log and re-throw
    console.error('Request failed:', error);
    throw error;
  }
}
```

### 6. Provide User-Friendly Error Messages [#6-provide-user-friendly-error-messages]

```javascript
function getUserFriendlyError(error) {
  const errorMessages = {
    'invalid_email': 'Please enter a valid email address.',
    'invalid_ip': 'Please enter a valid IP address.',
    'rate_limit_exceeded': 'Too many attempts. Please try again in a moment.',
    'invalid_api_key': 'Service configuration error. Please contact support.',
    'service_unavailable': 'Service temporarily unavailable. Please try again later.'
  };

  return errorMessages[error.error] || 'An unexpected error occurred. Please try again.';
}

// Usage in UI
try {
  await checkEmail(email);
} catch (error) {
  const userMessage = getUserFriendlyError(error);
  showErrorToUser(userMessage);
}
```

## Testing Error Handling [#testing-error-handling]

You can test your error handling by simulating different error conditions:

```javascript
// Test with invalid email
await checkEmail('not-an-email');

// Test with missing API key
await fetch('https://bifrost.api-armor.com/v1/check?email=test@example.com');

// Test with invalid API key
await fetch('https://bifrost.api-armor.com/v1/check?email=test@example.com', {
  headers: { 'Authorization': 'Bearer invalid_key' }
});
```

## Getting Help [#getting-help]

If you encounter persistent errors:

1. Check our [status page](https://status.api-armor.com) for service issues
2. Review this documentation for common solutions
3. Contact support with:
   * Error message and status code
   * Request details (without sensitive data)
   * Timestamp of the error
   * Your API key prefix (first 8 characters only)

## Next Steps [#next-steps]

- [Rate Limits](/docs/rate-limits): Learn about rate limiting

- [API Reference](/docs/api-reference): Complete API documentation

- [Authentication](/docs/authentication): API key management


---

# Rate Limits
URL: https://api-armor.com/docs/rate-limits

> Understanding API rate limits, usage tiers, and best practices for staying within your limits.

## Overview [#overview]

API Shield implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied per API key and vary based on your subscription plan.

## Rate Limit Tiers [#rate-limit-tiers]

### Free Tier [#free-tier]

Perfect for testing and small projects.

* **Requests:** 100 requests/month
* **Rate:** 10 requests/minute

### Developer Plan [#developer-plan]

For growing applications and startups.

* **Requests:** 10,000 requests/month
* **Rate:** 120 requests/minute

### Pro Plan [#pro-plan]

For production applications with steady traffic.

* **Requests:** 100,000 requests/month
* **Rate:** 200 requests/minute

> [View detailed pricing](/pricing) for all plans and features.

## How Rate Limiting Works [#how-rate-limiting-works]

Rate limits are enforced using a **sliding window** algorithm:

1. Each API key has a maximum number of requests allowed per time window
2. The window slides continuously rather than resetting at fixed intervals

### Example [#example]

With a limit of 120 requests/minute:

* You can make 20 requests within any 60-second period
* If you make 20 requests in the first 10 seconds, you must wait 50 seconds before making more
* The window slides continuously, not in fixed 1-minute blocks

## Rate Limit Headers [#rate-limit-headers]

Every API response includes rate limit information in the headers:

```http
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1699564800
```

### Header Descriptions [#header-descriptions]

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Remaining requests in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets      |

### Reading Rate Limit Headers [#reading-rate-limit-headers]

```javascript
const response = await fetch(
  'https://bifrost.api-armor.com/v1/check?email=test@example.com',
  {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  }
);

const rateLimit = {
  limit: response.headers.get('X-RateLimit-Limit'),
  remaining: response.headers.get('X-RateLimit-Remaining'),
  reset: response.headers.get('X-RateLimit-Reset')
};

console.log('Rate Limit Info:', rateLimit);

// Check if we're close to the limit
if (rateLimit.remaining < 10) {
  console.warn('Approaching rate limit!');
}
```

```python
response = requests.get(
    'https://bifrost.api-armor.com/v1/check',
    params={'email': 'test@example.com'},
    headers={'Authorization': f'Bearer {API_KEY}'}
)

rate_limit = {
    'limit': response.headers.get('X-RateLimit-Limit'),
    'remaining': response.headers.get('X-RateLimit-Remaining'),
    'reset': response.headers.get('X-RateLimit-Reset')
}

print(f"Rate Limit Info: {rate_limit}")

# Check if we're close to the limit
if int(rate_limit['remaining']) < 10:
    print("Warning: Approaching rate limit!")
```

## Rate Limit Exceeded Response [#rate-limit-exceeded-response]

When you exceed your rate limit, you'll receive a `429 Too Many Requests` response:

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```

The `retry_after` field indicates how many seconds you should wait before retrying.

## Best Practices [#best-practices]

### 1. Implement Client-Side Rate Limiting [#1-implement-client-side-rate-limiting]

Track your request rate and implement client-side throttling:

```javascript
class RateLimiter {
  constructor(maxRequests, windowMs) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
    this.requests = [];
  }

  async checkLimit() {
    const now = Date.now();
    
    // Remove requests outside the window
    this.requests = this.requests.filter(
      time => now - time < this.windowMs
    );

    // Check if we're at the limit
    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = this.requests[0];
      const waitTime = this.windowMs - (now - oldestRequest);
      
      // Wait until the oldest request expires
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return this.checkLimit();
    }

    // Add current request
    this.requests.push(now);
  }
}

// Usage
const limiter = new RateLimiter(20, 60000); // 20 req/min

async function checkEmail(email) {
  await limiter.checkLimit();
  
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );
  
  return await response.json();
}
```

### 2. Handle Rate Limit Errors Gracefully [#2-handle-rate-limit-errors-gracefully]

Implement exponential backoff when you hit rate limits:

```javascript
async function checkEmailWithBackoff(email, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const error = await response.json();
      const retryAfter = error.retry_after || Math.pow(2, i) * 1000;
      
      if (i < retries - 1) {
        console.log(`Rate limited. Waiting ${retryAfter}s before retry...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
    }

    throw new Error(`Request failed: ${response.status}`);
  }
}
```

### 3. Cache Results [#3-cache-results]

Reduce API calls by caching validation results:

```javascript
class EmailChecker {
  constructor(cacheTimeout = 24 * 60 * 60 * 1000) { // 24 hours
    this.cache = new Map();
    this.cacheTimeout = cacheTimeout;
  }

  async check(email) {
    // Check cache first
    const cached = this.cache.get(email);
    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
      console.log('Cache hit:', email);
      return cached.data;
    }

    // Make API request
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const data = await response.json();

    // Cache the result
    this.cache.set(email, {
      data,
      timestamp: Date.now()
    });

    return data;
  }
}

const checker = new EmailChecker();
```

### 4. Batch Processing with Delays [#4-batch-processing-with-delays]

When processing large batches of emails, add delays between requests:

```javascript
async function processBatch(emails, delayMs = 100) {
  const results = [];

  for (const email of emails) {
    try {
      const result = await checkEmail(email);
      results.push({ email, result });
      
      // Add delay between requests
      await new Promise(resolve => setTimeout(resolve, delayMs));
    } catch (error) {
      results.push({ email, error: error.message });
    }
  }

  return results;
}

// Process 100 emails with 100ms delay = ~10 requests/second
const results = await processBatch(emails, 100);
```

### 5. Use Request Queues [#5-use-request-queues]

For high-volume applications, implement a request queue:

```javascript
class RequestQueue {
  constructor(rateLimit, windowMs) {
    this.rateLimit = rateLimit;
    this.windowMs = windowMs;
    this.queue = [];
    this.processing = false;
  }

  async enqueue(request) {
    return new Promise((resolve, reject) => {
      this.queue.push({ request, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;
    
    this.processing = true;

    while (this.queue.length > 0) {
      const { request, resolve, reject } = this.queue.shift();

      try {
        const result = await request();
        resolve(result);
      } catch (error) {
        reject(error);
      }

      // Add delay to respect rate limits
      await new Promise(resolve => 
        setTimeout(resolve, this.windowMs / this.rateLimit)
      );
    }

    this.processing = false;
  }
}

// Usage
const queue = new RequestQueue(20, 60000); // 20 req/min

async function checkEmailQueued(email) {
  return queue.enqueue(async () => {
    const response = await fetch(
      `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );
    return await response.json();
  });
}
```

### 6. Monitor Your Usage [#6-monitor-your-usage]

Track your API usage in your [dashboard](/dashboard) to:

* Monitor requests per day/month
* Identify usage patterns
* Plan for plan upgrades
* Set up usage alerts

```javascript
// Log rate limit info with each request
async function checkEmailWithLogging(email) {
  const response = await fetch(
    `https://bifrost.api-armor.com/v1/check?email=${encodeURIComponent(email)}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const remaining = response.headers.get('X-RateLimit-Remaining');
  const limit = response.headers.get('X-RateLimit-Limit');
  const usagePercent = ((limit - remaining) / limit * 100).toFixed(1);

  console.log(`Rate limit usage: ${usagePercent}% (${remaining}/${limit} remaining)`);

  // Alert if usage is high
  if (usagePercent > 90) {
    console.warn('WARNING: Approaching rate limit!');
    // Send alert to monitoring system
  }

  return await response.json();
}
```

## Upgrading Your Plan [#upgrading-your-plan]

If you consistently hit rate limits, consider upgrading your plan:

1. Visit your [Dashboard](/dashboard)
2. Go to **Billing & Plans**
3. Select a higher tier
4. Changes take effect immediately

> Need custom limits? [Contact us](/contact) for Enterprise pricing with tailored rate limits and SLAs.

## Rate Limit FAQs [#rate-limit-faqs]

### Are rate limits per API key or per account? [#are-rate-limits-per-api-key-or-per-account]

Rate limits are applied **per API key**. You can create multiple API keys to separate usage across different applications or environments.

### What happens if I exceed my monthly quota? [#what-happens-if-i-exceed-my-monthly-quota]

When you reach your monthly request quota:

* Free tier: Requests will be rejected with a 429 error
* Paid plans: Additional requests are billed at your plan's overage rate
* You can upgrade your plan anytime for higher limits

### Do failed requests count towards my rate limit? [#do-failed-requests-count-towards-my-rate-limit]

* ✅ &#x2A;*Do count:** All requests that reach our servers, including those that return errors
* ❌ &#x2A;*Don't count:** Requests that fail due to network issues before reaching our servers

### Can I request a temporary rate limit increase? [#can-i-request-a-temporary-rate-limit-increase]

Yes! If you have a temporary need (e.g., data migration), [contact support](/contact) and we can arrange a temporary increase.

## Next Steps [#next-steps]

- [View Pricing](/pricing): Compare plans and features

- [API Reference](/docs/api-reference): Complete API documentation

- [Error Handling](/docs/errors): Handle rate limit errors properly


---

# Argus Overview
URL: https://api-armor.com/docs/argus

> Argus is an embeddable device-fingerprinting SDK. Identify and re-recognize visitors using unspoofable network signals fused with browser signals.

Argus is a **device-fingerprinting SDK** you embed in your website. Unlike Bifrost, it is **not** a REST API you call from your backend — you add one `<script>` tag and Argus identifies the visitor's device in the browser, returning a stable `argus_visitor_id`.

> **Plan requirement**
>
> Argus requires a **Developer or Pro** plan. Add and verify your domain in the [dashboard](/dashboard/argus) before embedding the snippet.

## How it works [#how-it-works]

Argus combines two classes of signal:

* **Server-derived (unspoofable).** When the browser connects, the Argus service reads the raw TLS handshake and HTTP/2 frames to compute **JA3 / JA4** and the **Akamai HTTP/2 fingerprint**. These are produced by the device's network stack and cannot be faked from JavaScript.
* **Client-collected.** The SDK gathers high-entropy browser signals — canvas, audio, WebGL, installed fonts, speech voices, platform — and sends them to the service.

The service fuses both into a **stable device identity** using fuzzy matching, so the same device is recognized across visits even when individual signals drift (for example, a browser version bump or Safari private mode).

- [Set up & verify your domain](/docs/argus/setup): Register a site, get your site-id, and verify domain ownership via DNS.

- [Quick start](/docs/argus/quick-start): One script tag, five minutes.

- [Response reference](/docs/argus/response): Every field Argus returns, and what it means.

- [Framework guides](/docs/argus/frameworks): HTML, Next.js, React, and Vue/Nuxt snippets.

## Privacy [#privacy]

Argus identifies **devices**, not people. Each fingerprint is scoped to your `site-id` — a visitor's identity on your site is isolated from every other site. The identity cookie (`aa_fp`) is a [CHIPS partitioned cookie](https://developer.mozilla.org/en-US/docs/Web/Privacy/Partitioned_cookies), so it is not shared across top-level sites. Document your use of Argus in your privacy policy as you would any analytics or anti-fraud tooling.


---

# Setup & Domain Verification
URL: https://api-armor.com/docs/argus/setup

> Register a site, get your site-id, and verify domain ownership with a DNS TXT record before embedding Argus.

Before you can embed Argus, register the website you want to fingerprint and prove you own its domain. This takes a few minutes plus DNS propagation time.

## Step 1: Add your domain [#step-1-add-your-domain]

1. Open the [Argus dashboard](/dashboard/argus).
2. Enter the domain you want to protect (for example `example.com`) and submit.
3. Argus issues a **site-id** that looks like `aa-argus-1a2b3c4d-...`. You'll put this on your `<script>` tag.

> **Re-adding is safe**
>
> Adding a domain you've already added just resumes the existing site — it never errors or double-counts. Deleting a site frees the domain so you can re-add it cleanly later.

## Step 2: Create the DNS TXT record [#step-2-create-the-dns-txt-record]

To prove you own the domain, add a TXT record. The dashboard shows the exact values; they follow this shape:

| Field       | Value                                                  |
| ----------- | ------------------------------------------------------ |
| Type        | `TXT`                                                  |
| Name / Host | `aa-argus-dfs.example.com`                             |
| Value       | the verification token shown in the dashboard (a UUID) |

> **Host label**
>
> The record name is the dedicated label &#x2A;*`aa-argus-dfs`** under your domain — like `_dmarc`. If your DNS provider asks only for the host portion (not the full name), enter `aa-argus-dfs`.

## Step 3: Verify [#step-3-verify]

Back in the dashboard, click **Verify**. Argus resolves `aa-argus-dfs.example.com` over DNS and checks the TXT value matches your token.

* **Success:** the site flips to verified and the snippet goes live.
* **Not yet:** DNS changes can take minutes to hours to propagate. Wait and retry. Double-check the host label and that the value is the raw token with no extra quotes.

## Next [#next]

- [Quick start](/docs/argus/quick-start): Embed the snippet now that your domain is verified.

- [Troubleshooting](/docs/argus/troubleshooting): Verification or origin errors? Start here.


---

# Quick Start
URL: https://api-armor.com/docs/argus/quick-start

> Add one script tag and start identifying visitors in five minutes.

Once your domain is [verified](/docs/argus/setup), embedding Argus is a single tag.

## Step 1: Add the script [#step-1-add-the-script]

Paste this just before your closing `</body>` tag (or in `<head>` with `async`). Replace the `site-id` value with the one from your [dashboard](/dashboard/argus):

```html
<script
  site-id="aa-argus-YOUR-SITE-ID"
  src="https://fpcdn.api-armor.com/js/dfs.min.js"
  async
></script>
```

That's it. On page load Argus collects signals, calls the fingerprint service, and exposes the result.

## Step 2: Read the result [#step-2-read-the-result]

Argus sets the result on `window.AAArgus` **after** the request finishes (it's `undefined` until then, and `null` if the request failed). Poll for it with a small helper:

```html
<script>
  function onArgus(cb, timeoutMs = 8000) {
    const start = Date.now();
    (function poll() {
      if (typeof window.AAArgus !== 'undefined') return cb(window.AAArgus);
      if (Date.now() - start > timeoutMs) return cb(null);
      setTimeout(poll, 100);
    })();
  }

  onArgus((result) => {
    if (!result) return; // failed or timed out
    console.log('Visitor:', result.argus_visitor_id);
    console.log('Bot score:', result.bot_score);
  });
</script>
```

See the [Response reference](/docs/argus/response) for every field.

## Step 3: Try debug mode [#step-3-try-debug-mode]

Add `debug="true"` to print a colored, boxed readout of the fingerprint to the browser console:

```html
<script
  site-id="aa-argus-YOUR-SITE-ID"
  debug="true"
  src="https://fpcdn.api-armor.com/js/dfs.min.js"
></script>
```

Open DevTools → Console (F12) to see the `argus_visitor_id`, JA4, IP, and the full payload. Remove `debug="true"` in production.

> **Testing locally**
>
> Argus works on `localhost`, `127.0.0.1`, and `[::1]` even though they aren't your registered domain — loopback origins are always allowed for development. Your site-id and plan still apply.

## Next [#next]

- [Framework guides](/docs/argus/frameworks): Next.js, React, and Vue/Nuxt integration.

- [Advanced usage](/docs/argus/advanced): Manual control, storage hints, and SPA re-identification.


---

# Framework Guides
URL: https://api-armor.com/docs/argus/frameworks

> Copy-paste Argus integration for plain HTML, Next.js, React, and Vue/Nuxt.

Every integration loads the same CDN tag and reads the asynchronously-populated `window.AAArgus`. Pick your stack.

## Plain HTML [#plain-html]

Put the tag before `</body>` (or in `<head>` with `async`):

```html
<script
  site-id="aa-argus-YOUR-SITE-ID"
  src="https://fpcdn.api-armor.com/js/dfs.min.js"
  async
></script>
<script>
  function onArgus(cb, timeoutMs = 8000) {
    const start = Date.now();
    (function poll() {
      if (typeof window.AAArgus !== 'undefined') return cb(window.AAArgus);
      if (Date.now() - start > timeoutMs) return cb(null);
      setTimeout(poll, 100);
    })();
  }
  onArgus((r) => r && console.log('Visitor:', r.argus_visitor_id));
</script>
```

## Next.js [#nextjs]

Use `next/script` with `strategy="afterInteractive"`. Custom attributes like `site-id` pass straight through.

```tsx
// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://fpcdn.api-armor.com/js/dfs.min.js"
          strategy="afterInteractive"
          site-id="aa-argus-YOUR-SITE-ID"
        />
      </body>
    </html>
  );
}
```

```tsx
// pages/_app.tsx
import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://fpcdn.api-armor.com/js/dfs.min.js"
        strategy="afterInteractive"
        site-id="aa-argus-YOUR-SITE-ID"
      />
    </>
  );
}
```

```tsx
'use client';
import { useEffect, useState } from 'react';

export function useArgus() {
  const [argus, setArgus] = useState<any>(null);
  useEffect(() => {
    const start = Date.now();
    const id = setInterval(() => {
      if (typeof (window as any).AAArgus !== 'undefined') {
        clearInterval(id);
        setArgus((window as any).AAArgus);
      } else if (Date.now() - start > 8000) {
        clearInterval(id);
      }
    }, 100);
    return () => clearInterval(id);
  }, []);
  return argus; // null until ready or on failure
}
```

## React (Vite / CRA) [#react-vite--cra]

Drop this typed hook into your project, then read `{ result, status }` from any component:

```ts
import { useEffect, useState } from 'react';

// What the Argus CDN bundle assigns to window.AAArgus.
export interface ArgusResult {
  argus_visitor_id: string;
  match_score: number;
  id_source: 'cookie' | 'storage' | 'fingerprint' | 'new';
  confidence: number;
  bot_score: number;
  network: {
    ja3?: string;
    ja3_hash?: string;
    ja4?: string;
    aa_dfs?: string;
    akamai?: string;
    http_version?: string;
    ip?: string;
    user_agent?: string;
  };
}

declare global {
  interface Window {
    AAArgus?: ArgusResult | null;
  }
}

type Status = 'loading' | 'ready' | 'failed';

// Injects the Argus tag once, then polls window.AAArgus until it
// resolves (`ready`) or fails / times out (`failed`).
export function useArgus(siteId: string, timeoutMs = 8000) {
  const [result, setResult] = useState<ArgusResult | null>(null);
  const [status, setStatus] = useState<Status>('loading');

  useEffect(() => {
    let script = document.querySelector<HTMLScriptElement>('script[data-argus]');
    if (!script) {
      script = document.createElement('script');
      script.src = 'https://fpcdn.api-armor.com/js/dfs.min.js';
      script.async = true;
      script.setAttribute('site-id', siteId);
      // Uncomment to print a colored fingerprint readout to the console:
      // script.setAttribute('debug', 'true');
      script.setAttribute('data-argus', '1');
      document.body.appendChild(script);
    }

    const started = Date.now();
    const id = window.setInterval(() => {
      if (window.AAArgus !== undefined) {
        clearInterval(id);
        if (window.AAArgus === null) setStatus('failed');
        else {
          setResult(window.AAArgus);
          setStatus('ready');
        }
      } else if (Date.now() - started > timeoutMs) {
        clearInterval(id);
        setStatus('failed');
      }
    }, 100);

    return () => clearInterval(id);
  }, [siteId, timeoutMs]);

  return { result, status };
}
```

```tsx
import { useArgus } from './lib/useArgus';

const SITE_ID = 'aa-argus-YOUR-SITE-ID';

export function App() {
  const { result, status } = useArgus(SITE_ID);

  if (status === 'loading') return <p>Identifying device…</p>;
  if (status === 'failed') return <p>Couldn't identify this device.</p>;

  return (
    <div>
      <p>Visitor: {result?.argus_visitor_id}</p>
      <p>Bot score: {result?.bot_score}</p>
    </div>
  );
}
```

## Vue / Nuxt [#vue--nuxt]

```ts
import { onMounted, onUnmounted, ref } from 'vue';

export function useArgus(siteId: string) {
  const argus = ref<any>(null);
  let id: ReturnType<typeof setInterval> | undefined;
  onMounted(() => {
    if (!document.querySelector('script[data-argus]')) {
      const s = document.createElement('script');
      s.src = 'https://fpcdn.api-armor.com/js/dfs.min.js';
      s.async = true;
      s.setAttribute('site-id', siteId);
      s.setAttribute('data-argus', '1');
      document.body.appendChild(s);
    }
    const start = Date.now();
    id = setInterval(() => {
      if (typeof (window as any).AAArgus !== 'undefined') {
        clearInterval(id);
        argus.value = (window as any).AAArgus;
      } else if (Date.now() - start > 8000) {
        clearInterval(id);
      }
    }, 100);
  });
  onUnmounted(() => clearInterval(id));
  return argus;
}
```

```ts
// plugins/argus.client.ts — runs only on the client
export default defineNuxtPlugin(() => {
  useHead({
    script: [
      {
        src: 'https://fpcdn.api-armor.com/js/dfs.min.js',
        async: true,
        'site-id': 'aa-argus-YOUR-SITE-ID',
      },
    ],
  });
});
```

> **Single-page apps**
>
> The tag fingerprints once per full page load, not per client-side route change. To re-identify on navigation, see [Advanced usage](/docs/argus/advanced).

## Next [#next]

- [Advanced usage](/docs/argus/advanced): SPA re-identification, storage hints, and the CHIPS cookie.

- [Response reference](/docs/argus/response): Every field Argus returns.


---

# Response Reference
URL: https://api-armor.com/docs/argus/response

> Every field Argus returns on window.AAArgus, what it means, and which signals are unspoofable.

A successful fingerprint resolves to an object on `window.AAArgus`. Example:

```json
{
  "argus_visitor_id": "9f2c…",
  "match_score": 0.94,
  "id_source": "cookie",
  "confidence": 0.88,
  "bot_score": 0.0,
  "network": {
    "ja3": "771,4865-4866-…",
    "ja3_hash": "cd08e31494f9531f560d64c695473da9",
    "ja4": "t13d1516h2_…",
    "aa_dfs": "…",
    "akamai": "1:65536,2:0,4:6291456|…",
    "http_version": "h2",
    "ip": "203.0.113.7",
    "user_agent": "Mozilla/5.0 …"
  }
}
```

## Top-level fields [#top-level-fields]

| Field              | Type         | Meaning                                                                                                                                              |
| ------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `argus_visitor_id` | string       | Stable device identity. Use this to recognize the device across visits.                                                                              |
| `match_score`      | number (0–1) | Similarity between this visit and the matched device record. `0` when a new device record was created this visit (no prior record to match against). |
| `id_source`        | string       | How the device was matched: `cookie`, `storage`, `fingerprint`, or `new`.                                                                            |
| `confidence`       | number (0–1) | How identifying the collected signal set is. Higher = more distinctive.                                                                              |
| `bot_score`        | number (0–1) | Automation likelihood. Higher = more bot-like (e.g. UA/TLS mismatch, missing canvas, headless tells).                                                |
| `network`          | object       | Server-derived network signals (see below).                                                                                                          |

### `id_source` values [#id_source-values]

* **`cookie`** — matched via the `aa_fp` cookie hint from a previous visit (cheapest path).
* **`storage`** — matched via the localStorage hint (`X-AA-FP-Storage` header) when the cookie was unavailable.
* **`fingerprint`** — no hint matched; matched by signal similarity against existing records.
* **`new`** — no match; a new device record was created this visit.

## `network` object [#network-object]

| Field          | Source     | Meaning                              |
| -------------- | ---------- | ------------------------------------ |
| `ja3`          | **server** | JA3 TLS fingerprint string.          |
| `ja3_hash`     | **server** | MD5 of the JA3 string.               |
| `ja4`          | **server** | JA4 TLS fingerprint.                 |
| `aa_dfs`       | **server** | PeetPrint-style TLS hash.            |
| `akamai`       | **server** | Akamai HTTP/2 fingerprint (h2 only). |
| `http_version` | **server** | `h2` or `http/1.1`.                  |
| `ip`           | **server** | Client IP as seen by the service.    |
| `user_agent`   | **server** | User-Agent header as received.       |

> **Server-derived signals are unspoofable**
>
> Every field in `network` is computed by the Argus service from the raw TLS/HTTP layers, not from JavaScript. A browser cannot fake them, which is why a UA that disagrees with the TLS fingerprint raises `bot_score`.

## The `aa_fp` cookie [#the-aa_fp-cookie]

On each response Argus sets a cookie so the next visit can take the cheap cookie path:

```
aa_fp=<argus_visitor_id>; Path=/; Max-Age=31536000; SameSite=None; Secure; Partitioned
```

It is a **CHIPS partitioned** cookie (`Partitioned`), so it is keyed to your site and not shared across top-level sites. `Secure` means it only flows over HTTPS.

## Next [#next]

- [Advanced usage](/docs/argus/advanced): Storage hints, the CHIPS cookie, and SPA re-identification.

- [Troubleshooting](/docs/argus/troubleshooting): Console messages and how to fix them.


---

# Advanced Usage
URL: https://api-armor.com/docs/argus/advanced

> SPA re-identification, storage hints, and the CHIPS cookie.

The CDN tag covers most integrations. These topics are for finer control.

## Re-identifying in single-page apps [#re-identifying-in-single-page-apps]

The CDN tag fingerprints once per full page load. To re-run on a client-side route change, re-insert the script (the simplest reliable approach), then read `window.AAArgus` again:

```js
function reidentify(siteId) {
  document.querySelector('script[data-argus]')?.remove();
  delete window.AAArgus;
  const s = document.createElement('script');
  s.src = 'https://fpcdn.api-armor.com/js/dfs.min.js';
  s.async = true;
  s.setAttribute('site-id', siteId);
  s.setAttribute('data-argus', '1');
  document.body.appendChild(s);
}
```

> **Do you need this?**
>
> A device's `argus_visitor_id` doesn't change between routes, so most apps fingerprint once and reuse the value. Re-identify only if you want a fresh `bot_score`/`match_score` per view.

## How re-recognition works: hints [#how-re-recognition-works-hints]

To recognize a returning device cheaply, Argus stores the `argus_visitor_id` in two places and sends them back on the next request:

* **Cookie** — the `aa_fp` CHIPS cookie (see [Response reference](/docs/argus/response)). Sent automatically because the request uses `credentials: 'include'`.
* **localStorage** — a fallback the SDK reads and sends as the `X-AA-FP-Storage` header when the cookie is missing (e.g. cookies cleared but storage intact).

If either hint matches, `id_source` is `cookie` or `storage`. Otherwise Argus falls back to signal-similarity matching.

> **Cross-origin credentials**
>
> Argus is hosted on a different origin than your site, so the cookie is cross-origin. The SDK sends requests with `credentials: 'include'`; the service echoes your `Origin` and sets `Access-Control-Allow-Credentials: true`. Browser settings that block all third-party/partitioned cookies will force the localStorage hint or signal-matching path.


---

# Troubleshooting
URL: https://api-armor.com/docs/argus/troubleshooting

> Argus console messages, HTTP statuses, local testing, and a "nothing happens" checklist.

Argus logs a short message to the console on failure. Match it below.

## Error reference [#error-reference]

| Console message                                             | HTTP        | Cause                                                                                   | Fix                                                                                        |
| ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `Invalid or unverified site-id.`                            | 401         | The site-id isn't found, the domain isn't verified, or the site is banned.              | Finish [domain verification](/docs/argus/setup) and confirm the site-id is copied exactly. |
| `Please upgrade your account at https://api-armor.com`      | 402         | The account's plan isn't Developer or Pro.                                              | Upgrade your plan.                                                                         |
| `This domain is not registered for the provided site-id.`   | 403         | The request's `Origin` doesn't match the verified domain (and isn't a loopback origin). | Embed the snippet on the verified domain or a subdomain of it.                             |
| `Fingerprint request failed.`                               | 503 / other | The service or its datastore is temporarily unavailable.                                | Retry; if it persists, check status and contact support.                                   |
| `Missing site-id attribute on the dfs.min.js <script> tag.` | —           | The `site-id` attribute is absent or empty on the tag.                                  | Add `site-id="aa-argus-…"` to the `<script>` tag.                                          |

## Testing locally [#testing-locally]

You don't need to deploy to test. Loopback origins are always allowed:

* `http://localhost:3000` (and any `*.localhost`)
* `http://127.0.0.1`
* `http://[::1]`

Your site-id and plan still apply, but the origin check is skipped, so the snippet works on your dev server even though the origin isn't your registered domain.

## Debug mode [#debug-mode]

Add `debug="true"` to the tag to print a colored readout (and a one-time DevTools nudge) to the console:

```html
<script
  site-id="aa-argus-YOUR-SITE-ID"
  debug="true"
  src="https://fpcdn.api-armor.com/js/dfs.min.js"
></script>
```

On failure, debug mode also prints the error body, which includes the `type` (`auth`, `payment`, `origin`, `unavailable`) — match it to the table above.

## "Nothing happens" checklist [#nothing-happens-checklist]

* **No `site-id`?** The SDK logs the missing-attribute message and stops. Add the attribute.
* **`window.AAArgus` is `undefined`?** It's populated asynchronously — poll with the `onArgus` helper from [Quick start](/docs/argus/quick-start). `undefined` = still running; `null` = failed.
* **Script never loads?** Check your Content-Security-Policy allows `script-src https://fpcdn.api-armor.com`, and that an ad-blocker isn't blocking it.
* **Works locally but 403 in production?** The production origin must match the verified domain — re-check the domain you registered.