POSTJECTDOCS

Security Features

Protect your Postject account with two-factor authentication, IP whitelisting, and automated anomaly detection.

Two-Factor Authentication (2FA)

Add an extra layer of security to your account with time-based one-time passwords (TOTP). Use any authenticator app like Google Authenticator, Authy, or 1Password.

Enabling 2FA

To enable 2FA, first generate a secret and QR code:

bash
POST /v1/auth/2fa/generate
Authorization: Bearer <your_jwt_token>

# Response:
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,..."
}

Scan the QR code with your authenticator app, then enable 2FA by verifying a token:

bash
POST /v1/auth/2fa/enable
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "token": "123456"
}

# Response:
{
  "message": "2FA enabled successfully",
  "backupCodes": [
    "a3f7d9e2c1b8",
    "f4c9a7b1d3e8",
    ...
  ]
}

Backup Codes

Save your backup codes in a secure location. Each code can be used once to log in if you lose access to your authenticator app. Once all backup codes are used, generate new ones from your account settings.

Logging In with 2FA

When 2FA is enabled, you must provide a token after entering your password:

bash
POST /v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "yourpassword",
  "twoFactorToken": "123456"
}

Disabling 2FA

bash
POST /v1/auth/2fa/disable
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "token": "123456"
}

IP Whitelisting

Restrict API access to specific IP addresses or CIDR ranges. When enabled, all requests from non-whitelisted IPs are rejected with a 403 Forbidden error.

Adding IPs to Whitelist

bash
POST /v1/auth/ip-whitelist
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "ip": "203.0.113.42"
}

CIDR Notation Support

You can whitelist entire IP ranges using CIDR notation:

bash
POST /v1/auth/ip-whitelist
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "ip": "192.168.1.0/24"
}

# This allows all IPs from 192.168.1.0 to 192.168.1.255

Viewing Whitelist

bash
GET /v1/auth/ip-whitelist
Authorization: Bearer <your_jwt_token>

# Response:
{
  "whitelist": [
    "203.0.113.42",
    "192.168.1.0/24"
  ]
}

Removing IPs

bash
DELETE /v1/auth/ip-whitelist
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "ip": "203.0.113.42"
}

Important

If your whitelist is not empty, only requests from whitelisted IPs will be allowed. Make sure to add your current IP before enabling this feature to avoid locking yourself out. You can manage up to 50 IP addresses or ranges.

Anomaly Detection

Postject automatically monitors your account activity and alerts you to suspicious behavior. Our system uses multiple detection algorithms to identify potential security threats in real-time.

Detection Algorithms

Request Spike Detection

Alerts when API request volume exceeds 5x the 7-day average within a 1-hour window. Helps identify compromised API keys or DDoS attempts.

Geographic Change

Detects login attempts from new geographic locations not seen in your recent activity. Flags potential account takeover attempts.

Unusual Endpoint Access

Monitors access to sensitive endpoints like billing, API key management, and admin routes. Alerts on excessive access (>10 requests/hour).

Brute Force Protection

Tracks failed login attempts and blocks IPs after 5 failed attempts within 1 hour. Automatically lifts the block after 24 hours.

Viewing Security Alerts

bash
GET /v1/security/alerts
Authorization: Bearer <your_jwt_token>

# Response:
{
  "alerts": [
    {
      "id": "alert_abc123",
      "type": "request_spike",
      "severity": "high",
      "description": "Unusual spike in API requests detected",
      "metadata": {
        "normalRate": 120,
        "currentRate": 650,
        "window": "1 hour"
      },
      "createdAt": "2025-07-15T10:30:00.000Z",
      "resolved": false
    }
  ],
  "total": 1
}

Resolving Alerts

Once you have investigated and addressed a security alert, mark it as resolved:

bash
PATCH /v1/security/alerts/:alertId
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "resolved": true
}

Email Notifications

High-severity security alerts are automatically sent to your account email address. You can configure notification preferences in your account settings.

Activity Logs

All API requests and account actions are logged for security auditing. Logs include the IP address, user agent, endpoint accessed, and timestamp.

bash
GET /v1/security/activity-logs
Authorization: Bearer <your_jwt_token>

# Query parameters:
# - limit: Number of logs (max 1000, default 100)
# - offset: Pagination offset
# - startDate: Filter by date range
# - endDate: Filter by date range

# Response:
{
  "logs": [
    {
      "id": "log_xyz789",
      "action": "send_email",
      "ipAddress": "203.0.113.42",
      "userAgent": "PostjectSDK/1.0.0",
      "metadata": {
        "messageId": "msg_abc123"
      },
      "createdAt": "2025-07-15T10:30:00.000Z"
    }
  ],
  "total": 1234
}