Build with the HumanShield API
Powerful REST API to integrate security awareness training, phishing simulations, and risk management into your existing workflows.
Developer-Friendly API
Built with modern standards and best practices for seamless integration
Secure Authentication
JWT-based authentication with refresh token rotation
RESTful Design
Clean, predictable endpoints following REST principles
Comprehensive Coverage
Full CRUD operations for all platform resources
Multi-tenant Ready
Built-in organization isolation and access control
Rate Limiting
Fair usage policies with clear rate limit headers
OpenAPI Spec
Full OpenAPI 3.0 specification for easy integration
Authentication
Secure JWT-based authentication with refresh tokens
Getting Started
- 1Obtain API KeyGenerate an API key from your dashboard settings
- 2AuthenticateExchange credentials for access token (15min) and refresh token (7d)
- 3Make RequestsInclude access token in Authorization header
Authorization: Bearer YOUR_ACCESS_TOKENAPI Endpoints Overview
Comprehensive REST API covering all platform features
Users & Organizations
/api/v1/usersList all users
/api/v1/usersCreate a new user
/api/v1/users/:idGet user details
/api/v1/users/:idUpdate user
/api/v1/users/:idDelete user
Training Campaigns
/api/v1/training/campaignsList campaigns
/api/v1/training/campaignsCreate campaign
/api/v1/training/assignmentsGet assignments
/api/v1/training/assignmentsAssign training
Phishing Simulations
/api/v1/phishing/campaignsList phishing campaigns
/api/v1/phishing/campaignsCreate campaign
/api/v1/phishing/resultsGet campaign results
/api/v1/phishing/templatesList templates
Analytics & Reporting
/api/v1/analytics/risk-scoresGet risk scores
/api/v1/analytics/eventsQuery events
/api/v1/analytics/reportsGenerate report
/api/v1/analytics/metricsGet metrics
Code Examples
Get started quickly with examples in your favorite language
cURL
# Authenticate
curl -X POST https://api.humanshield.io/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@company.com",
"password": "your-password"
}'
# List users
curl -X GET https://api.humanshield.io/v1/users \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Create a phishing campaign
curl -X POST https://api.humanshield.io/v1/phishing/campaigns \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Q4 Phishing Test",
"templateId": "template_123",
"targetGroups": ["sales", "finance"],
"scheduledDate": "2025-12-01T09:00:00Z"
}'JavaScript / TypeScript
// Install the SDK
// npm install @humanshield/sdk
import { HumanShield } from '@humanshield/sdk';
// Initialize client
const client = new HumanShield({
apiKey: process.env.HUMANSHIELD_API_KEY,
baseUrl: 'https://api.humanshield.io/v1'
});
// Authenticate
const { accessToken } = await client.auth.login({
email: 'admin@company.com',
password: 'your-password'
});
// List users
const users = await client.users.list({
page: 1,
limit: 50,
department: 'engineering'
});
// Create phishing campaign
const campaign = await client.phishing.campaigns.create({
name: 'Q4 Phishing Test',
templateId: 'template_123',
targetGroups: ['sales', 'finance'],
scheduledDate: '2025-12-01T09:00:00Z'
});
console.log('Campaign created:', campaign.id);Python
# Install the SDK
# pip install humanshield
from humanshield import HumanShield
# Initialize client
client = HumanShield(
api_key=os.getenv('HUMANSHIELD_API_KEY'),
base_url='https://api.humanshield.io/v1'
)
# Authenticate
auth = client.auth.login(
email='admin@company.com',
password='your-password'
)
# List users
users = client.users.list(
page=1,
limit=50,
department='engineering'
)
# Create phishing campaign
campaign = client.phishing.campaigns.create(
name='Q4 Phishing Test',
template_id='template_123',
target_groups=['sales', 'finance'],
scheduled_date='2025-12-01T09:00:00Z'
)
print(f'Campaign created: {campaign.id}')Rate Limits
Standard tier - perfect for most integrations
Enterprise tier - for high-volume applications
Rate limit headers included in all responses. Contact us for custom limits.
Official SDKs
@humanshield/sdkhumanshieldgithub.com/humanshield/go-sdkhumanshield-rubyReady to Start Building?
Get API access and start integrating HumanShield into your workflows today.
Free tier includes 1,000 requests/hour. No credit card required.