Skip to main content

Authenticate

availability

Deployment: Invicti Platform on-demand, Invicti Platform on-premises

Part of API fundamentals series

This is part 3 of 5 in the API fundamentals series.
Previous: Get your API key | Next: Make your first call

Invicti Platform API authentication uses your personal API key to authorize requests. This document explains how to authenticate API calls, manage your API key securely, and troubleshoot authentication issues.

API authentication method​

X-Auth API Key

  • Uses your personal API key from user settings
  • Recommended approach for all API usage
  • Works with all standard API endpoints
  • Simpler setup and management

X-Auth API key authentication​

This is the primary and recommended authentication method for all API usage. It uses your personal API key directly in a custom header.

X-Auth header format​

X-Auth: YOUR_API_KEY
  • X-Auth: Custom header name used by Invicti Platform
  • YOUR_API_KEY: Your unique API key from User settings > API key (see Manage your API key)

X-Auth examples​

curl:

curl -X GET "https://platform.invicti.com/api/1.0/targets" \
  -H "X-Auth: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json"

Python requests:

headers = {
    "X-Auth": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://platform.invicti.com/api/1.0/targets",
    headers=headers
)

Postman:

  1. Go to Authorization tab
  2. Select API Key type
  3. Set Key to X-Auth and Value to your API key
  4. Choose Header for where to add it

API key characteristics​

Format: JSON Web Token (JWT)

  • Your API key is a JWT that contains encoded information about your identity and permissions
  • Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI...
  • Used directly in X-Auth header

Scope: User-specific

  • Invicti Platform ties each API key to a specific user account
  • The key inherits the permissions of the associated user
  • Invicti Platform logs all operations under the key owner's identity

Permissions: Role-based

  • API access depends on your user role (Owner, Admin, etc.)
  • Some endpoints require specific permissions (for example scan management, user administration)
  • Check with your administrator if you get permission errors

API key lifecycle​

Your API key goes through three stages: generation, active use, and management or revocation.

1. Key generation​

  • Generated through the web interface (User settings > API key) - see Manage your API key for steps
  • Only one active key per user at a time
  • Generating a new key immediately invalidates the previous one

2. Key usage​

  • Use directly in X-Auth header for all operations
  • Valid until explicitly deleted or regenerated
  • No automatic expiration (remains active indefinitely)

3. Key management​

  • View current key in user settings (partially masked for security)
  • Copy full key value when needed
  • Delete key to revoke all API access
  • Regenerate key if compromised

Security best practices​

Follow these practices to keep your API key secure and limit exposure if it's compromised.

Protect your API key​

# Good: Use environment variables
export INVICTI_API_KEY="your-api-key-here"
curl -H "X-Auth: $INVICTI_API_KEY" ...

# Bad: Hard-coded in scripts
curl -H "X-Auth: eyJ0eXAiOiJKV1QiLCJhbG..." ...

Secure storage approaches​

  • Environment variables: For local development and server deployments
  • Secret management systems: For production environments (AWS Secrets Manager, Azure Key Vault, etc.)
  • CI/CD variables: For automated deployments and testing
  • Configuration files: Only if properly secured and not in version control

Access control​

  • Principle of least privilege: Only grant necessary permissions to API users
  • Regular audits: Periodically review which users have API keys
  • Key rotation: Regenerate keys periodically or when team members leave

Common authentication errors​

If your API call fails with an authentication error, check the status code and follow the guidance below.

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Causes:

  • Missing authentication header (X-Auth)
  • Incorrect header format
  • Invalid or expired API key
  • API key deleted or regenerated

Solutions:

  • Verify header format: X-Auth: YOUR_KEY
  • Check API key is current and correctly copied
  • Regenerate API key if necessary

403 Forbidden​

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this operation"
}

Causes:

  • Valid authentication but inadequate permissions
  • User role doesn't allow the requested operation
  • X-Auth API key lacks specific permissions

Solutions:

  • Check your user role and permissions
  • Contact administrator for role adjustments
  • Verify operation is available for your account type

Testing authentication​

Use the following request to verify your API key is working correctly.

Test X-Auth authentication:​

curl -H "X-Auth: YOUR_API_KEY" \
  https://platform.invicti.com/api/identity/v1/me

Expected success response:

  • Status: 200 OK
  • Body: Your user information
  • Confirms both connectivity and authentication

Next steps​

With authentication concepts mastered, you're ready to put them into practice:

→ Continue to Make your first call

Complete fundamentals series​

Need help?​

Invicti Support team is ready to provide you with technical help. Go to Help Center

Last updated on
Was this page useful?