Authentication overview

LinkPreview utilizes an API key-based authentication system to secure access to its Link Preview API. This mechanism ensures that only authorized applications can send requests and retrieve link metadata. An API key acts as a unique identifier and a secret token, which must be included with every API call to authenticate the client. This approach is common for many web services due to its simplicity and ease of implementation, particularly for server-side applications where the key can be securely stored. The API key allows LinkPreview to track usage, enforce rate limits, and provide access to features based on the user's subscription plan, starting with a free tier of 500 requests per month and scaling up with paid plans LinkPreview pricing plans.

When integrating with LinkPreview, developers are responsible for the secure handling of their API keys. This includes preventing unauthorized disclosure and ensuring keys are not exposed in client-side code or public repositories. The LinkPreview documentation provides specific instructions on how to obtain and use these credentials effectively within various programming environments LinkPreview API documentation.

Supported authentication methods

The LinkPreview API primarily supports a single authentication method: API Key authentication. This method is straightforward and involves passing a unique key with each request to the API.

API Key Authentication

API Key authentication for LinkPreview involves generating a unique string from your account dashboard and including it in your API requests. This key serves as both an identifier for your application and a secret for verifying your access rights. It is typically passed as a query parameter in the API request URL.

The table below summarizes the key authentication method:

Method When to Use Security Level
API Key (Query Parameter) Server-side applications, backend services, scripting environments Moderate (requires secure key management)

While API keys offer convenience, it is crucial to manage them securely to prevent unauthorized access. Best practices for API key management include restricting key access, using environment variables, and rotating keys periodically. For more general information on API key security, refer to resources like the OWASP API Security Project OWASP API Security Top 10.

Getting your credentials

To authenticate with the LinkPreview API, you will need to obtain an API key from your LinkPreview account dashboard. The process is designed to be straightforward:

  1. Sign Up or Log In: Navigate to the LinkPreview homepage and either create a new account or log in to an existing one.
  2. Access Dashboard: Once logged in, you will typically be directed to your user dashboard.
  3. Locate API Key Section: Look for a section labeled 'API Key', 'Developer Settings', or similar. This section usually contains your unique API key.
  4. Generate/Copy Key: If a key is not already displayed, there might be an option to generate a new one. Otherwise, copy the existing API key provided. Keep this key secure and do not share it publicly.
  5. Review Documentation: For specific instructions and any recent changes to the credential retrieval process, always consult the official LinkPreview documentation.

Your API key is essential for making authenticated requests. Treat it like a password and protect it from unauthorized access.

Authenticated request example

This section demonstrates how to make an authenticated request to the LinkPreview API using your API key. The examples show how to include the API key as a query parameter, which is the standard method for LinkPreview. The API supports various SDKs including Node.js, PHP, Python, and Ruby LinkPreview SDKs.

Node.js Example

Using the node-fetch library for an HTTP request:


const fetch = require('node-fetch');

const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const urlToPreview = 'https://example.com';

async function getLinkPreview() {
  try {
    const response = await fetch(`https://api.linkpreview.net/?key=${apiKey}&q=${encodeURIComponent(urlToPreview)}`);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error fetching link preview:', error);
  }
}

getLinkPreview();

Python Example

Using the requests library:


import requests

api_key = 'YOUR_API_KEY'  # Replace with your actual API key
url_to_preview = 'https://example.com'

params = {
    'key': api_key,
    'q': url_to_preview
}

try:
    response = requests.get('https://api.linkpreview.net/', params=params)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error fetching link preview: {e}")

PHP Example

Using file_get_contents or cURL:


<?php
$apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
$urlToPreview = 'https://example.com';

$requestUrl = 'https://api.linkpreview.net/?key=' . $apiKey . '&q=' . urlencode($urlToPreview);

$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => 'Accept: application/json\r\n'
    ]
]);

try {
    $response = @file_get_contents($requestUrl, false, $context);
    if ($response === FALSE) {
        throw new Exception('Failed to retrieve data from LinkPreview API.');
    }
    $data = json_decode($response, true);
    print_r($data);
} catch (Exception $e) {
    echo 'Error fetching link preview: ' . $e->getMessage();
}
?>

Ruby Example

Using the net/http library:


require 'net/http'
require 'uri'
require 'json'

api_key = 'YOUR_API_KEY' # Replace with your actual API key
url_to_preview = 'https://example.com'

uri = URI("https://api.linkpreview.net/")
uri.query = URI.encode_www_form({
  'key' => api_key,
  'q' => url_to_preview
})

begin
  response = Net::HTTP.get_response(uri)
  if response.is_a?(Net::HTTPSuccess)
    data = JSON.parse(response.body)
    puts data
  else
    puts "HTTP Error: #{response.code} - #{response.message}"
  end
rescue StandardError => e
  puts "Error fetching link preview: #{e.message}"
end

In all examples, remember to replace 'YOUR_API_KEY' with your actual API key obtained from the LinkPreview dashboard and 'https://example.com' with the URL you wish to preview.

Security best practices

Securing your LinkPreview API key is crucial to prevent unauthorized usage, protect your account, and maintain the integrity of your application. Adhering to these best practices will help mitigate common security risks:

  • Never Expose API Keys in Client-Side Code: Do not embed your API key directly in client-side JavaScript, mobile applications, or any code that is publicly accessible. An exposed API key can be stolen and used by malicious actors, leading to unauthorized charges or abuse of service. Always proxy requests through your own backend server if client-side initiation is necessary.
  • Use Environment Variables for Server-Side Keys: For server-side applications, store your API key in environment variables rather than hardcoding it directly into your source code. This practice prevents the key from being committed to version control systems like Git and keeps it separate from your application logic. Most hosting platforms offer secure ways to manage environment variables.
  • Restrict API Key Usage (if applicable): While LinkPreview's API keys are generally tied to your account for all requests, if LinkPreview were to introduce features allowing IP address restrictions or domain whitelisting for API keys, you should configure these immediately. This limits where your API key can be used, adding an extra layer of security. Always check the LinkPreview documentation for any updates on key restriction features.
  • Implement HTTPS for All API Calls: Always ensure that all communications with the LinkPreview API are conducted over HTTPS. This encrypts the data in transit, protecting your API key and the content of your requests and responses from eavesdropping and man-in-the-middle attacks. LinkPreview's API endpoints are designed to be accessed via HTTPS, which is a fundamental security measure HTTPS security overview.
  • Rotate API Keys Periodically: Regularly generating a new API key and revoking the old one reduces the window of opportunity for a compromised key to be exploited. While there isn't an automatic rotation feature, manually rotating keys every few months or after significant team changes is a good practice.
  • Monitor API Usage: Keep an eye on your API usage statistics within the LinkPreview dashboard. Unusual spikes in usage could indicate that your API key has been compromised. Timely detection allows you to revoke the key and investigate the issue.
  • Secure Your Development Environment: Ensure that the machines and systems where your API key is stored or used are secure. This includes using strong passwords, enabling multi-factor authentication, and keeping software up to date to protect against vulnerabilities.
  • Avoid Logging API Keys: Do not log your API keys in plain text within your application's logs. If debugging requires logging, ensure that sensitive information like API keys is redacted or masked.

By following these best practices, you can significantly enhance the security posture of your application's integration with the LinkPreview API.