GeographQL Authentication: API Key & GraphQL Security (2026)

Authentication overview

GeographQL secures access to its GraphQL API primarily through API keys. These keys serve as a unique identifier for your application and authorize your requests to GeographQL's geocoding and reverse geocoding services. All requests to the GeographQL API must be made over HTTPS to ensure data encryption in transit.

The API key model is a common approach for GraphQL APIs, providing a straightforward method for client applications to authenticate without requiring complex user credential flows. When an API key is included with a request, GeographQL verifies the key's validity and associated permissions before processing the GraphQL query or mutation. This system helps manage access control and monitor API usage across different applications and users.

For detailed information on API key management and usage, refer to the official GeographQL documentation.

Supported authentication methods

GeographQL supports API key authentication for all access to its GraphQL API. This method involves including a unique key in each request to verify the client's identity and authorization. The simplicity of API keys makes them suitable for server-to-server communication and client-side applications where the key can be securely managed.

While API keys are the primary method, it's essential to understand their implications for security, especially in different deployment environments. For public clients, additional safeguards are often necessary to prevent key exposure. The table below outlines the key authentication method supported by GeographQL:

GraphQL APIs often utilize distinct authentication mechanisms compared to REST APIs. While REST might frequently employ OAuth 2.0 for user delegation, GraphQL's single-endpoint nature means that API keys or token-based authentication (like JWTs) are common for identifying the calling application or user directly. The GraphQL authorization guide further discusses these patterns.

Getting your credentials

To access GeographQL's services, you must first obtain an API key. This key is provisioned through your GeographQL account dashboard.

1. Sign Up/Log In: Navigate to the GeographQL homepage and either sign up for a new account or log in to an existing one. GeographQL offers a free tier that includes 1,000 requests per month, which also requires an API key for access.
2. Access Dashboard: Once logged in, you will be directed to your user dashboard.
3. Locate API Key Section: Within the dashboard, look for a section labeled 'API Keys' or 'Developer Settings'.
4. Generate Key: If you do not have an existing key, there will be an option to generate a new API key. Follow the on-screen prompts to create your key.
5. Securely Store Key: Once generated, your API key will be displayed. It is crucial to copy this key immediately and store it securely. GeographQL may only display the full key once for security reasons.

Your API key is directly linked to your account's usage limits and billing, as outlined on the GeographQL pricing page. It is recommended to manage your keys diligently and regenerate them periodically, especially if you suspect compromise or as part of routine security practices.

Authenticated request example

Authenticating with GeographQL involves sending your API key in the Authorization HTTP header of your GraphQL requests. The key should be prefixed with Bearer, following common token-based authentication patterns.

cURL Example

This example demonstrates a basic geocoding query using cURL, authenticating with an API key:

curl -X POST \
  https://api.geographql.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{ "query": "query { geocode(address: \"1600 Amphitheatre Parkway, Mountain View, CA\") { latitude longitude } }" }'

Replace YOUR_API_KEY with your actual GeographQL API key. The Authorization: Bearer header is essential for the request to be successfully authenticated.

JavaScript (Fetch API) Example

For client-side or server-side JavaScript applications, you can use the Fetch API to make authenticated requests:

const API_KEY = 'YOUR_API_KEY';
const GEOGRAPHQL_ENDPOINT = 'https://api.geographql.com/graphql';

async function geocodeAddress(address) {
  const query = `
    query {
      geocode(address: \"${address}\") {
        latitude
        longitude
        formattedAddress
      }
    }
  `;

  try {
    const response = await fetch(GEOGRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({ query })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Geocoding Result:', data.data.geocode);
    return data.data.geocode;
  } catch (error) {
    console.error('Error during geocoding:', error);
    return null;
  }
}

geocodeAddress('Eiffel Tower, Paris, France');

In this JavaScript example, the API key is embedded directly. For production applications, especially in client-side contexts, consider environment variables or secure server-side proxies to prevent direct exposure of your API key in client-side code bundles. More examples and detailed API specifications are available in the GeographQL API reference.

Security best practices

Securing your GeographQL integration involves more than just obtaining an API key. Implementing robust security practices is crucial to protect your data, prevent unauthorized access, and manage your API usage responsibly.

• Keep API Keys Confidential: Treat your GeographQL API key like a password. Never hardcode it directly into client-side code that will be publicly distributed (e.g., in web or mobile applications). For client-side use, consider proxying requests through your own backend server or using environment variables during development and deployment.
• Use Environment Variables: Store API keys in environment variables on your server or build system. This practice prevents keys from being committed to version control systems like Git and keeps them out of your codebase.
• Server-Side Proxy: For web applications, route all GeographQL API requests through your own backend server. Your server can then add the API key before forwarding the request to GeographQL. This completely shields the API key from the client application.
• Least Privilege: If GeographQL introduces fine-grained access controls in the future, configure API keys with the minimum necessary permissions. This limits the potential damage if a key is compromised.
• Regular Key Rotation: Periodically rotate your API keys. This means generating a new key and updating your applications to use it, then revoking the old key. This practice reduces the window of opportunity for a compromised key to be exploited.
• Monitor API Usage: Regularly check your GeographQL dashboard for unusual API usage patterns. Spikes in requests or usage from unexpected locations could indicate a compromised key.
• HTTPS Only: Always ensure your requests to GeographQL are made over HTTPS. This encrypts the communication channel, protecting your API key and data from interception during transit. This is also a fundamental requirement for secure communication on the web, as detailed by the Mozilla Developer Network's HTTPS explanation.
• Error Handling: Implement robust error handling for authentication failures. Do not expose sensitive error messages to end-users that could reveal information about your authentication mechanism or API key.

Adhering to these practices will significantly enhance the security posture of your applications integrating with GeographQL, protecting both your data and your account resources.