Authentication overview

IPS Online secures access to its suite of computer vision APIs, including Image Tagging, Object Detection, Facial Recognition, and Content Moderation, primarily through the use of API keys. This approach verifies the identity of the client making API requests, ensuring that resources are accessed only by authenticated applications and users. Authentication is a prerequisite for all interactions with the IPS Online API, regardless of whether a user is operating on the free tier or a paid plan.

The system is designed to provide a balance between ease of integration for developers and robust security. By requiring an API key for every request, IPS Online maintains control over API usage, monitors for potential abuse, and enforces rate limits specific to each account. The integration process is streamlined with comprehensive API reference documentation and SDKs available in multiple programming languages, simplifying the inclusion of authentication headers in API calls.

Supported authentication methods

IPS Online's API supports a single, consistent authentication method across all its services: API Keys. This method is widely adopted for its simplicity and effectiveness in securing API endpoints for many web services.

API Keys

API keys are unique, secret tokens that identify an application or user when making requests to the IPS Online API. When an application sends a request, the API key is included in the request headers or as a query parameter. The IPS Online server then validates this key against its records to determine if the request is authorized. If the key is valid and active, the request proceeds; otherwise, it is rejected with an authentication error.

  • Mechanism: API keys are typically passed in the Authorization HTTP header as a Bearer token or sometimes as a custom header, or query parameter (though header transmission is generally preferred for security).
  • Purpose: They serve as a straightforward method to control access, track usage, and manage quotas for individual users or applications.
  • Security Considerations: While easy to implement, API keys are bearer tokens and should be treated with the same confidentiality as passwords. They provide access to an account's resources, so their compromise can lead to unauthorized access and potential misuse of services.

Authentication Methods Table

Method When to Use Security Level
API Key (Bearer Token) All API interactions with IPS Online Medium (high if handled securely, e.g., server-side)

Getting your credentials

Accessing the IPS Online API requires an API key, which can be generated and managed through your IPS Online account dashboard. The process is designed to be self-service, allowing developers to quickly obtain the necessary credentials to begin integrating with the API.

Steps to obtain an API Key:

  1. Sign Up/Log In: Navigate to the IPS Online homepage and either create a new account or log in to an existing one.
  2. Access Dashboard: Once logged in, go to your personal dashboard. This is typically accessible via a link like "My Account" or "Dashboard" in the navigation menu.
  3. Locate API Key Section: Within the dashboard, look for a section dedicated to API keys or developer settings. The exact naming might vary but commonly includes terms like "API Credentials," "Developer Keys," or "Settings."
  4. Generate New Key: If you don't have an existing key or wish to generate a new one for a specific application, there will be an option to "Generate New API Key" or similar. Clicking this usually provides you with a unique alphanumeric string.
  5. Copy and Secure Your Key: Immediately after generation, copy your API key. For security reasons, often the key is only displayed once. It is crucial to store this key securely, as it grants access to your IPS Online account's API usage.

IPS Online's official documentation provides detailed, step-by-step instructions with screenshots for generating and managing API keys. It is recommended to consult this resource for the most up-to-date guidance.

Authenticated request example

Once you have obtained your API key, you can include it in your API requests. The primary method for authenticating requests to IPS Online is by including the API key in the Authorization header as a Bearer token. This is a common pattern for securing RESTful APIs, as described in RFC 6750 for Bearer Token Usage.

Here's an example of how to make an authenticated request using the Python SDK for the Image Tagging API.

Python Example (using requests library)

First, ensure you have the requests library installed (pip install requests).


import requests
import json

API_KEY = "YOUR_IPS_ONLINE_API_KEY"
API_ENDPOINT = "https://api.ipsonline.net/v1/image/tag"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Example: Tagging an image from a URL
payload = {
    "image_url": "https://example.com/image.jpg"
}

try:
    response = requests.post(API_ENDPOINT, headers=headers, data=json.dumps(payload))
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)

    response_data = response.json()
    print("Image Tagging Results:")
    print(json.dumps(response_data, indent=2))

except requests.exceptions.HTTPError as e:
    print(f"HTTP error occurred: {e}")
    print(f"Response content: {e.response.text}")
except requests.exceptions.ConnectionError as e:
    print(f"Connection error occurred: {e}")
except requests.exceptions.Timeout as e:
    print(f"Timeout error occurred: {e}")
except requests.exceptions.RequestException as e:
    print(f"An unexpected error occurred: {e}")

Node.js Example (using axios library)

First, ensure you have the axios library installed (npm install axios).


const axios = require('axios');

const API_KEY = "YOUR_IPS_ONLINE_API_KEY";
const API_ENDPOINT = "https://api.ipsonline.net/v1/image/tag";

const headers = {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
};

// Example: Tagging an image from a URL
const payload = {
    "image_url": "https://example.com/image.jpg"
};

axios.post(API_ENDPOINT, payload, { headers })
    .then(response => {
        console.log("Image Tagging Results:");
        console.log(JSON.stringify(response.data, null, 2));
    })
    .catch(error => {
        if (error.response) {
            // The request was made and the server responded with a status code
            // that falls out of the range of 2xx
            console.error(`HTTP error occurred: ${error.response.status}`);
            console.error(`Response data: ${JSON.stringify(error.response.data, null, 2)}`);
        } else if (error.request) {
            // The request was made but no response was received
            console.error("No response received:", error.request);
        } else {
            // Something happened in setting up the request that triggered an Error
            console.error("Error setting up request:", error.message);
        }
    });

Replace YOUR_IPS_ONLINE_API_KEY with your actual API key and https://example.com/image.jpg with the URL of the image you wish to process. Other API endpoints, such as those for Object Detection or Facial Recognition, will follow a similar authentication pattern but may require different payload structures.

Security best practices

Securing your API keys and the overall interaction with the IPS Online API is crucial to prevent unauthorized access and potential misuse of your account. Adhering to these best practices will help maintain the integrity and confidentiality of your API integrations.

1. Keep API Keys Confidential

  • Do not embed keys directly in client-side code: API keys embedded in publicly accessible client-side code (e.g., JavaScript in a web browser, mobile app binaries) can be easily extracted by malicious users. All API calls requiring authentication should ideally originate from your secure backend servers.
  • Environment variables: Store API keys as environment variables on your server or in secure configuration files that are not committed to version control systems like Git.
  • Secret management services: For larger applications, consider using secret management services provided by cloud providers (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) or dedicated tools like HashiCorp Vault.

2. Use HTTPS/TLS Always

  • All communication with the IPS Online API should exclusively use HTTPS/TLS. This encrypts data in transit, protecting your API key and other sensitive information from interception. IPS Online's API endpoints are designed to enforce HTTPS.

3. Implement Rate Limiting and Monitoring

  • Client-side rate limiting: Implement rate limiting on your application's side to prevent accidental bursts of requests that might exceed IPS Online's limits, potentially leading to temporary blocks or cost overruns.
  • Monitor API usage: Regularly review your API usage logs and metrics provided by IPS Online. Unusual spikes in usage could indicate a compromised key or an application error.

4. Rotate API Keys Regularly

  • Periodically generate new API keys and deprecate old ones. This practice minimizes the window of opportunity for a compromised key to be exploited.
  • If you suspect an API key has been compromised, immediately revoke it from your IPS Online dashboard and replace it with a newly generated key.

5. Restrict Key Permissions (if available)

  • While IPS Online primarily uses single-purpose API keys, if future features allow for granular permissions (e.g., a key only for Image Tagging, not Content Moderation), always configure keys with the minimum necessary permissions required for the task.

6. Secure Your Development Environment

  • Ensure that your development machines and build pipelines are secure. Unsecured development environments can be a vector for API key exfiltration.

By following these best practices, developers can significantly enhance the security posture of their applications integrating with IPS Online, safeguarding both their data and their account resources.