Authentication overview

The Randommer API provides programmatic access to a suite of random data generation endpoints, allowing developers to create mock data for various purposes such as testing, populating databases, and generating dummy content Randommer Documentation. To ensure secure and managed access to its services, Randommer implements an API key-based authentication system. This mechanism verifies the identity of the client making the request and enforces usage limits based on their subscription tier.

API keys serve as a simple yet effective method for client authentication in scenarios where user-specific authorization is not required, focusing instead on application-level access control. When an API key is used, the server identifies the application or developer account associated with that key and grants access to the requested resources, provided the key is valid and the request adheres to any rate limits or permissions configured for that key. The IETF RFC 7235 defines the HTTP Authorization header for carrying credentials, although API keys often use custom headers HTTP/1.1 Authentication RFC.

Supported authentication methods

Randommer primarily supports API key authentication. This method involves generating a unique alphanumeric string (the API key) from your Randommer account dashboard and including it in the HTTP headers of every request you send to the API.

API Key Authentication

API key authentication is a common method for securing access to web services. It functions by requiring clients to present a unique, secret key with each API request. This key acts as a token that identifies the calling application or user account. Randommer uses a custom HTTP header for this purpose.

  • How it works: You obtain an API key from your Randommer account. This key is then sent in the X-Api-Key HTTP header with every request to the Randommer API.
  • Purpose: Identifies the application/user, tracks usage against quotas (e.g., 1000 requests/day for the free tier Randommer Homepage), and grants access to paid features.
  • Advantages: Simple to implement, easy to manage, and widely understood by developers.
  • Disadvantages: Requires careful handling as the key itself acts as the credential. If an API key is compromised, it can be used by unauthorized parties until revoked.

Table: Randommer Authentication Methods

Method When to Use Security Level
API Key (HTTP Header) All API interactions with Randommer Moderate (relies on key secrecy)

Getting your credentials

To authenticate with the Randommer API, you need to obtain an API key from your Randommer account. The process is straightforward:

  1. Create a Randommer Account: If you do not already have one, navigate to the Randommer website and sign up for a new account. A free tier is available, offering up to 1000 requests per day.
  2. Log In: Once your account is created and verified, log in to your Randommer dashboard.
  3. Navigate to API Key Section: Within your dashboard, look for a section related to 'API Keys', 'Developer Settings', or 'Account Settings'. The exact navigation may vary but is typically clearly labeled.
  4. Generate Your API Key: Follow the instructions to generate a new API key. Randommer will typically display your newly generated key once. Copy this key immediately and store it securely, as it may not be displayed again for security reasons. If it's lost, you'll generally need to generate a new one.
  5. Store Securely: Treat your API key as a sensitive credential, similar to a password. Do not hardcode it directly into client-side code, commit it to version control, or expose it in public repositories.

For detailed, up-to-date instructions, always refer to the official Randommer Documentation.

Authenticated request example

Once you have obtained your API key, you can include it in the X-Api-Key HTTP header for every request to the Randommer API. The following example demonstrates how to make a request to the /Name endpoint to generate a random name using curl, a common command-line tool for making HTTP requests.

Replace YOUR_API_KEY with the actual API key you generated from your Randommer dashboard.

curl -X GET "https://randommer.io/api/Name?nameType=fullname&quantity=1"
     -H "Accept: application/json"
     -H "X-Api-Key: YOUR_API_KEY"

This request asks for one full name. The -H "X-Api-Key: YOUR_API_KEY" part is crucial for authentication. Without a valid API key in this header, the API will reject the request, typically with an HTTP 401 Unauthorized or 403 Forbidden status code.

For client-side development, ensure your application or server-side component securely manages and transmits this header. For instance, in a Node.js application using axios:

const axios = require('axios');

const API_KEY = process.env.RANDOMMER_API_KEY; // Stored securely as an environment variable

axios.get('https://randommer.io/api/Name?nameType=fullname&quantity=1', {
  headers: {
    'Accept': 'application/json',
    'X-Api-Key': API_KEY
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error fetching random name:', error.response ? error.response.data : error.message);
});

This example demonstrates retrieving the API key from an environment variable, which is a recommended practice for keeping sensitive credentials out of source code.

Security best practices

Securing your API keys is critical to prevent unauthorized access to your Randommer account and services. Adhering to these best practices helps mitigate common security risks:

  • Keep API Keys Confidential: Treat your API key like a password. Never embed it directly in client-side code (e.g., JavaScript running in a browser) or publicly accessible source code repositories.
  • Use Environment Variables: Store API keys in environment variables on your server or build system. This prevents them from being committed into version control systems like Git. For example, in a Linux/macOS environment, you can export export RANDOMMER_API_KEY="YOUR_KEY".
  • Avoid Hardcoding: Do not hardcode API keys directly into your application's source code. This makes key rotation difficult and increases the risk of exposure if the code is compromised.
  • Server-Side Access Only: Make API calls to Randommer from your backend server, not directly from client-side applications. This way, your API key is never exposed to the end-user's browser or device.
  • Restrict IP Addresses (If Available): If Randommer offers the option to restrict API key usage to specific IP addresses, configure this setting. This ensures that even if your key is compromised, it can only be used from trusted server environments. The Cloudflare API Token documentation provides a good example of IP address restrictions for API keys.
  • Monitor Usage: Regularly check your Randommer dashboard for unusual API usage patterns. Spikes in requests or unexpected endpoint calls could indicate a compromised key.
  • Rotate Keys Periodically: Periodically generate a new API key and replace the old one in your applications. This reduces the window of opportunity for a compromised key to be exploited.
  • Revoke Compromised Keys Immediately: If you suspect an API key has been compromised, revoke it immediately from your Randommer dashboard and generate a new one.
  • Implement Rate Limiting and Circuit Breakers: While Randommer handles its own rate limiting, implementing client-side rate limiting and circuit breakers in your application can prevent accidental overuse of the API and protect against potential denial-of-service (DoS) attacks if your key is exposed.
  • Secure Development Practices: Follow general secure coding practices, including input validation and proper error handling, to prevent vulnerabilities that could lead to API key exposure.