Authentication

All NINJIO API endpoints require authentication using an API key. This guide covers how to authenticate your requests and manage your API credentials.

API Key Authentication

Getting Your API Key

To generate an API key, you'll need to be an administrator on the NINJIO platform:

1. Login to the admin interface at https://admin.goninjio.com/

2. Click on Integration at the top right side of the screen

   

3. Click the New API Key button

4. Fill out the form:

   • Name your API key
   • Select your read and write preferences for the access points you wish to use

   

5. Click Generate Key

6. Important: Copy the key immediately and store it somewhere safe - it can only be viewed once

API keys are unique per customer account and should be kept secure.

Using Your API Key

Include your API key in the request header:

GET /api/api_gateway/3.0.0/customer/campaigns/training/
Host: apigw.goninjio.com
apiKey: YOUR_API_KEY_HERE
Content-Type: application/json

Example with cURL

curl -X GET "https://apigw.goninjio.com/api/api_gateway/3.0.0/customer/campaigns/training/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Example with JavaScript

const response = await fetch('https://apigw.goninjio.com/api/api_gateway/3.0.0/customer/campaigns/training/', {
  method: 'GET',
  headers: {
    'apiKey': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Example with Python

import requests

headers = {
    'apiKey': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://apigw.goninjio.com/api/api_gateway/3.0.0/customer/campaigns/training/',
    headers=headers
)

data = response.json()

Scopes

An API key does not grant access to everything. When you create one you choose read and write access per area, and those choices become the key's scopes. Every endpoint names the scope it requires at the top of its reference page, for example:

Required scope: employee.read

A call to an endpoint whose scope your key does not hold is refused with 403 — before the request reaches the application, so no data is touched. The scope is checked against the key, not against the account: holding employee.read lets you list employees for the account the key belongs to, and no other.

A few endpoints require more than one scope, because their response spans more than one area. GET /customer/groups/dynamic/by-name/{name}/ returns both phishing and training dynamic groups, so it requires phishing.dynamic.group.read and aware.dynamic.group.read. All listed scopes must be present; extra scopes on the key are harmless.

Diagnosing a 403

A 403 means one of three things: the apiKey header is missing, the key is not recognised, or the key lacks a scope the endpoint requires. Check the endpoint's Required scope line against the access points selected when the key was created, and regenerate the key if it needs an area it was not given.

Fields that can be null

Several response fields are nullable, and the reference page for each endpoint marks them. They are genuinely empty rather than missing — a campaign that has been created but never scheduled has start_date: null, an employee may have no phone, and a simulation that belongs to no campaign has campaign_id: null.

Decode into a type that permits null for those fields rather than assuming a string or a date, and treat null as "not set" rather than as an error.

Security Best Practices

Protecting Your API Key

• Never commit API keys to version control
• Store keys in environment variables or secure configuration
• Use different keys for development and production environments
• Rotate keys regularly

Environment Variables

# .env file
NINJIO_API_KEY=your_api_key_here
NINJIO_BASE_URL=https://apigw.goninjio.com

import os
import requests

api_key = os.getenv('NINJIO_API_KEY')
base_url = os.getenv('NINJIO_BASE_URL')

headers = {'apiKey': api_key}

Rate Limits

• Standard rate limits apply to all API endpoints
• Contact support if you need higher rate limits for your integration
• Implement exponential backoff for retries

Error Handling

Authentication Errors

{
  "error": "Invalid API key",
  "status": 401
}

{
  "error": "API key required",
  "status": 401
}

Example Error Handling

if (response.status === 401) {
  console.error('Authentication failed - check your API key');
  // Handle authentication error
} else if (response.status === 403) {
  console.error('Access forbidden - insufficient permissions');
  // Handle permission error
}

Testing Your Authentication

Use this simple test to verify your API key works:

curl -X GET "https://apigw.goninjio.com/api/api_gateway/3.0.0/customer/campaigns/training/" \
  -H "apiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

A successful response indicates your authentication is working correctly.