Quick Start Guide
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
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
First, you'll need an API key to authenticate your requests.
- Sign up for a free account
- Navigate to your dashboard
- Generate a new API key
- 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
Let's make a simple request to check if an email is disposable:
curl "https://bifrost.api-armor.com/v1/check?email=test@example.com" \
-H "Authorization: Bearer aa_abc123xyz789"Step 3: Handle the Response
The API returns a simple JSON response:
{
"email": "layohe8924@badfist.com",
"is_disposable": true,
"domain": "badfist.com",
"free_email": false
}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
Here's a complete example of integrating API Shield into a signup form:
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>
);
}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
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
In addition to email validation, you can also get IP intelligence to protect against malicious traffic, VPNs, and hosting providers.
Basic IP Intelligence Check
curl "https://bifrost.api-armor.com/v1/ip-reputation-check?ip=159.89.165.46" \
-H "Authorization: Bearer aa_abc123xyz789"Response
The IP intelligence endpoint returns comprehensive data:
{
"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
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);
}
});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.