API Authentication

Learn how to authenticate with the PhishFortress API using API keys and OAuth 2.0

Authentication Overview

PhishFortress API supports two authentication methods: API Keys for server-to-server communication and OAuth 2.0 for user-facing applications. All API requests must be authenticated to ensure security and proper access control.

Security Best Practices

Always use HTTPS when making API requests. Never expose API keys in client-side code or public repositories.

API Key Authentication

API keys are the recommended method for server-to-server integrations and automated scripts.

Generating an API Key

Log in to your PhishFortress dashboard
Navigate to Settings → API Keys
Click "Generate New API Key"
Provide a descriptive name for the key
Select the appropriate permissions/scopes
Copy and securely store the generated key

Important

API keys are only displayed once during generation. Store them securely as they cannot be retrieved later.

OAuth 2.0 Authentication

OAuth 2.0 is recommended for user-facing applications that need to access PhishFortress on behalf of users.

OAuth 2.0 Flow

Authorization Code Grant flow for web applications

Authorization Request: Redirect user to PhishFortress authorization server
User Consent: User logs in and grants permissions to your application
Authorization Code: PhishFortress redirects back with authorization code
Token Exchange: Exchange authorization code for access token
API Access: Use access token to make authenticated API requests

OAuth Endpoints

Authorization: https://auth.phishfortress.com/oauth/authorize

Token: https://auth.phishfortress.com/oauth/token

Application Registration

Go to Settings → OAuth Applications in your PhishFortress dashboard
Click "Create New Application"
Provide application name and description
Set redirect URIs for your application
Select required scopes/permissions
Save and note the Client ID and Client Secret

Redirect URIs

Redirect URIs must use HTTPS in production. For development, localhost URLs are permitted.

Code Examples

Here are examples of how to authenticate with the PhishFortress API in different programming languages.

JavaScript/Node.js

const axios = require('axios');

const apiKey = 'your_api_key_here';
const baseURL = 'https://api.phishfortress.com/v1';

const client = axios.create({
  baseURL,
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

// Example: Get all campaigns
async function getCampaigns() {
  try {
    const response = await client.get('/campaigns');
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

Error Handling

The PhishFortress API uses standard HTTP status codes to indicate the success or failure of requests.

Status Code	Description	Common Causes
200	OK	Request successful
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has expired",
    "details": {
      "timestamp": "2024-01-15T10:30:00Z",
      "request_id": "req_abc123"
    }
  }
}

Testing Your Authentication

Use this simple endpoint to verify that your authentication is working correctly.

Authentication Test Endpoint

Test Request

GET https://api.phishfortress.com/v1/auth/verify

Expected Response

{
  "authenticated": true,
  "user": {
    "id": "user_123",
    "email": "admin@company.com",
    "organization": "Acme Corp"
  },
  "permissions": ["campaigns:read", "campaigns:write", "users:read"]
}

Campaigns API