Developer API

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

  1. 1
    Obtain API Key
    Generate an API key from your dashboard settings
  2. 2
    Authenticate
    Exchange credentials for access token (15min) and refresh token (7d)
  3. 3
    Make Requests
    Include access token in Authorization header
Authorization Header
Authorization: Bearer YOUR_ACCESS_TOKEN

API Endpoints Overview

Comprehensive REST API covering all platform features

Users & Organizations

GET
/api/v1/users

List all users

POST
/api/v1/users

Create a new user

GET
/api/v1/users/:id

Get user details

PUT
/api/v1/users/:id

Update user

DELETE
/api/v1/users/:id

Delete user

Training Campaigns

GET
/api/v1/training/campaigns

List campaigns

POST
/api/v1/training/campaigns

Create campaign

GET
/api/v1/training/assignments

Get assignments

POST
/api/v1/training/assignments

Assign training

Phishing Simulations

GET
/api/v1/phishing/campaigns

List phishing campaigns

POST
/api/v1/phishing/campaigns

Create campaign

GET
/api/v1/phishing/results

Get campaign results

GET
/api/v1/phishing/templates

List templates

Analytics & Reporting

GET
/api/v1/analytics/risk-scores

Get risk scores

GET
/api/v1/analytics/events

Query events

POST
/api/v1/analytics/reports

Generate report

GET
/api/v1/analytics/metrics

Get 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

1,000
requests per hour

Standard tier - perfect for most integrations

10,000
requests per hour

Enterprise tier - for high-volume applications

Rate limit headers included in all responses. Contact us for custom limits.

Official SDKs

JavaScript / TypeScript
@humanshield/sdk
Available
Python
humanshield
Available
Go
github.com/humanshield/go-sdk
Coming Soon
Ruby
humanshield-ruby
Coming Soon

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